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Preface 



This publication has two objectives. The Planning por- 
tion provides guidance in selecting, planning for, and/ 
or evaluating os/vsi (virtual storage). The Use portion 
provides guidance in using some of the features or 
functions of the system. The Planning portion is for use 
by installation personnel who are familiar with ibm 
System/ 360 and who are considering the installation of 
an IBM System/ 370. The Use portion is directed to 
system programmers who maintain and/ or extend the 
system. 

The Planning portion contains two sections: Con- 
cepts and Considerations. The Concepts section briefly 
describes the functions, features, and device support 
provided by vsi. It also describes the operating princi- 
ples of the system. The Considerations section contains 
suggestions concerning selection of various options of 
the control program and suggestions concerning oper- 
ations in various modes (batch, teleprocessing, and 
graphics). 



Appendix A contains a brief theory of operation of 
the system. A glossary of vsi terms is also provided. 

The reader of the Planning portion should be famil- 
iar with the IBM System/ 370 System Summary, GA22- 
7001. The Introduction to Virtual Storage in System/ 
370, GR20-4260 will also be helpful, as will the OS/VS 
Virtual Storage Access Method Planning Guide, GC26- 
3799. For a complete list of available publications, see 
the IBM System/ 360 and System/ 370 Bibliography, 
GA22-6822. 

The Use portion of the Guide contains information 
on implementing and/ or extending some of the func- 
tions of the system. Each section in the Use portion is 
self-contained and deals with a separate capability or 
function of the control program. 

The reader of the Use portion is assumed to have 
the prerequisite background in programming and sys- 
tem maintenance required to implement the proce- 
dures contained in the Guide. 



Second Edition (January 1973) 

This edition applies to Release 2 of OS /VSI and to all subsequent releases until 
otherwise indicated in new editions or Technical Newsletters. Any references that 
are made to OS/VS2 appear for planning purposes only. Changes are continually 
made to the information contained herein; before using this publication in con- 
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Summary of Amendments 

for GC24-5090-1 

0S/VS1, Release 2 



Use Guide Reorganization 

The Use portion of the Planning and Use Guide has 
been rearranged. The sections are now placed in 
alphabetic sequence for easier access. 

TCAM Compatibility Restrictions 

Under Compatibility, Restrictions (planning por- 
tion), the documentation for TCAM object decks 
has been modified. 

Level II of TCAM will not run under Release 2 of 
VSl. The TCAM information in this book is included 
for planning purposes until the availability of TCAM 
Level IV. 

VSl Supported Devices 

Additional devices supported under VSl are included 
in the planning portion. 

Automated System Initialization 

An overview of the automated system initialization 
feature is given in the planning section. A new sec- 
tion, ASI, is added to the Use Guide. 

Remote Entry Services (RES) 

A planning overview of RES is included in the plan- 
ning portion. Utilization of Reader/Writer proced- 
ures by RES users is explained in section PRO of the 
Use Guide. Information on WTO/WTOR for RES 
users is included in section SMI. 

Missing Interruption Checker (MIC) 

A brief description of this program is given in the 
planning portion. Additional information is given 
under section FEA of the Use Guide. 

V— p f^ran Specification 

The topic Virtual=Real Storage Availability has been 
modified for V=R specification. 

Automatic Partition Redefinition 

In the planning portion of this manual, the topic 
Partition Redefinition has been updated. In the use 
portion, section FEA includes Automatic Partition 
Redefinition. 

Pageable System Queue Area (PSQA) 

Virtual storage area for PSQA is shown in the plan- 
ning portion in the figures for storage configurations. 

12K Dump Area 

Virtual storage for a 12K dump area is shown in the 
figures for storage configurations in the planning 
portion. 

Partition Deactivation/Reactivation 

This new topic is included under Operating Con- 
siderations in the planning portion of this manual. 

Page Boundary Loading 

Loading on page boundaries is briefly discussed 
under General Considerations in the planning section. 

Operator Commands 

The new operator commands DUMP, MSGRT, and 



STOPMN are listed under the topic Operator 
Commands. 

OS/MFT— OS/VSl Differences 

Section DIF has been updated to include additional 
MFT— VSl differences. 

Dynamic Dispatching 

This optional feature is explained in section FEA 
of the Use portion. 

Dynamic Support System (DSS) (for planning 

purposes cniyy 

DSS information is included in section FEA of the 
Use Guide. 

Greenwich Mean Time 

This feature is explained in section FEA of the Use 
Guide. 

User Modify Logical Cylinder 

Using this option is explained in section FEA of the 
Use Guide. 

ABEND Dump for Reader/Writer 

DD statements for Reader/Writer ABEND dumps 
are included in section PRO, 

Procedure INITD 

Section PRO contains an updated INITD procedure. 

Checkpointing SYSOUT Data Sets 

Information on this topic is included in section PRO. 

Resident Routines Option 

Lists lEABLDOO, lEAIGGOO, and lEARSVOO (IBM- 
supphed standard Hsts for BLDL, RAM, and RSVC) 
have been modified in section RRO. 

Output Separation 

End of job output separators information has been 
added to section SEP of the Use Guide. 

I/O Load Balancing 

I/O load balancing for non-specific requests is in- 
cluded in the Features and Options (FEA) section. 

DEB Validity Checking 

A brief explanation of this is given in section FEA. 

Message Routing Changes 

Changes for multiple-line WTO and miscellaneous 
items have been made in section MSG. 

Real Storage Restriction Removal 

The OLTEP not supported has been removed for 
144K systems. 

Miscellaneous 

Miscellaneous additions, improvements, and correc- 
tions have been made throughout this manual. 
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Introduction 



vsi provides support for ibm Systein/370 computing 
systems at the intermediate level. This support is com- 
parable to that provided in the non-relocate environ- 
ment by the System/ 360 Operating System with Multi- 
programming with a Fixed Number of Tasks (os mft). 
Several enhancements are included in vsi that make 
it a more eflFective and versatile operating system. Two 
of the more significant of these enhancements are Vir- 
tual Storage and Job Entry Subsystem. 

Note: Throughout this manual, the suffix "K" denotes the 
value 400 (hexadecimal), or 1024 (decimal). 



Virtual Storage 

Virtual storage provides the user with a storage capac- 
ity of up to 16,777,216 bytes, which he can use to oper- 
ate his computing system. (With the minimum 128K 
real storage system, the user is limited to two mega- 
bytes, or 2,097,152 bytes, of virtual storage.) The vir- 
tual storage is contained on auxiliary storage devices 
( direct access storage devices ) in units of 2048 bytes, 
referred to as pages. These pages are transferred into 
and out of real storage ( that part of the system storage 
from which the cpu can directly obtain instructions 
and data and to which it can directly return results) 
with relocation ( address translation ) to available areas 
of real storage, as they are needed by the system or by 
the user's programs. The process is called paging. 
Page-in obtains a page from auxihary storage and 
page-out returns a page to auxiliary storage. This pag- 
ing is handled by the vsi control program and is 
completely transparent to the user. ( Operating systems 
that do not support virtual storage are referred to as 
non-relocate systems. ) For a comprehensive discussion 
of virtual storage and the paging process, refer to the 
IBM System/370 System Summary, GA22-7001, in the 
section titled Virtual Storage and to the Introduction 
to Virtual Storage in System/370, GR20-4260. 



Advantages of VSI Virtual Storage 

• Jobs requiring more address space than the avail- 
able real storage can execute in an vsi environment. 

• Real storage can be dynamically allocated on an 
as-used or as-required basis. 

• Real storage that was unused, by partitions, in an 
OS MFT system can be recovered with vsi and used 



by other partitions, because virtual address space 
in a partition does not require real storage until it is 
addressed. 

• The small partition scheduling requirements of os 
MFT do not exist in vsi because virtual address 
space suflScient for scheduler requirements is pro- 
vided for all partitions. Thus, no partition is forced 
to wait for scheduling by another. 

• Programs with large design points can be tested 
on machines with smaller real storage. The per- 
formance of these programs will be directly related 
to their storage requirements versus real storage 
availabihty. 

• Future processors can be written for vsi with few 
storage restrictions. 

• Infrequently executed system tasks do not require 
real storage to be permanently reserved for their 
use. These programs can be paged in on demand. 

• Virtual storage can be reserved for unscheduled 
top-priority jobs. 

• Partition redefinition requirement is reduced. 



Job Entry Subsystem 

The Job Entry Subsystem ( jes ) is the name of a cen- 
tralized system facihty that provides spooling and 
scheduling of vsi primary input and output streams. 
Priority command routing and new operator com- 
mands simplify many operator tasks. 

JES performs three basic functions: 

1. All primary input streams are read from the input 
device and stored on a direct access storage device 
in a format convenient for later processing by the 
system and by user's programs. 

2. System (and selected user) print and punch output 
is similarly stored on a direct access storage device 
until a convenient time for printing or punching. 

3. If system resources are the objects of contention, 
JES schedules the activities to assure the highest 
degree of system availability. 

The first two of the preceding functions are referred 
to as spooling. Spooling provides the following advan- 
tages: 
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• Non-sharable devices, generally unit record devices, 
are used at full rated speed if enough buffers are 
available. 

• Non-sharable devices are used only for the time 
required to read, print, or punch the data. 

Without spooling, the device is occupied for the 
entire time that a job is reading input or writing out- 
put. Thus, the device runs only as fast as the job can 
accept or generate data. 

Because data is stored on a direct access storage 
device, jobs or their output can be processed in a dif- 
ferent order from that in which they were submitted. 
This abiHty to control system work is called job queue- 
ing. Jobs can be scheduled by class, and by priority 
within class. 

The ability to spool input and output and to queue 
jobs significantly improves system performance and 
configurability by centralizing and scheduling heavily 
used functions and by utilizing resources more effi- 
ciently. Other improvements, such as reduced system 
overhead, simpler operator procedures, and increased 
system availability are possible through the use of 
the Job Entry Subsystem. Certain portions of jes are 
more fully discussed in this publication in the Concepts 
section under the headings Input Readers, and Out- 
put Writers. 

Compatibility 

Current os mft object programs will execute in vsi 
virtual storage with the exceptions of those noted here 
in Restrictions. Some programs may require virtual= 
real execution and will not use demand paging. ( This is 
covered more fully in the Concepts section of this book 
under the heading Virtual=Real Execution.) Current 
OS data sets will process in the vsi system without mod- 
ification or conversion. 

Sequentially organized dos data sets ( sam ) that are 
portable between dos and os mft without conversion 
or other user intervention will be fully portable be- 
tween DOS and vsi. 

VSI is upward compatible to vs2. This compatibility 
includes source program code, object program code, 
job control language, and conventions and standards. 
For a description of os/vsi-os/vs2 differences, refer to 
the 0S/VS2 Planning and Use Guide, GC 28-0600. 

Restrictions 

Existing os programs that will not operate under vsi 
without modification include those that: 

1. Are time-dependent. 

2. Are written to deliberately cause program excep- 
tions. 



3. Use machine-dependent data. 

4. Use the program status word (psw) bit 12 (the 
Ascnbit). 

5. Use low-address storage reserved for special pur- 
poses (psw). 

6. Depend on devices or faciHties not supported or 
available in System/ 370 or vsi. 

7. Require model-dependent System/360 functions. 

8. Attempt to read or write sysin or sysout data by 
other than the sam access method (that is, excp 
will not work on these data sets ) . 

9. Depend on a valid ucb pointer in the hot for 
sysin/ sysout data sets. 

10. Include tcam object decks, tcam message control 
programs and tcam message processing programs 
using the icopy, tcopy, qcopy, and tchng macro 
instructions must be reassembled and linkage 
edited, tcam message processing programs not 
using any of these macro instructions need only 
to be re-linkage edited. 

The Use part of this publication contains a resume 
of some of the more significant differences between 
os/mft and os/vsi. This resume is the section OS/ 
MFT-OS/VSl Differences. It will be of particular in- 
terest to system programmers who are involved in an 
mft to vsi conversion. 

Real Storage Restrictions 

vsi requires 160K bytes of available real storage to sup- 
port the standard features listed under Standard and 
Optional Features in this publication. Lack of avail- 
able real storage reduces the capabilities of vsi. For 
example, the following restrictions apply to the 128K 
real storage configuration: 

• Only one partition is supported. 

• The generalized trace facility, dynamic support 
system (dss), and oltep are not supported. 

• A maximum of two megabytes of virtual storage 
may be specified. 

For the 144K real storage configuration, the follow- 
ing restrictions apply: 

• Two-partition support is the recommended maxi- 
mum. 

• The external trace option of the generalized trace 
facility is not supported. 



The Planning Guide 

The Concepts section of this publication is intended 
for data processing executives responsible for selection 
of a system, and planners and system analysts who 



10 OS/ VSI Planning and Use Guide 



must understand its operation to plan for its efficient 
use, and to establish installation procedures. To accom- 
plish this, the Concepts section presents a sample 
sequence of operation describing the initiation, execu- 
tion, and termination of a set of jobs of various cate- 
gories and priorities. This sequence of operation is 
followed by a description of the principles of operation 
of the vsi system, describing the operation of each 
major component of the system. 

The Considerations section contains information of 
interest to data processing executives, planners, and 
system analysts. It also describes vsi considerations 
of interest to system programmers who will estabHsh 
programming conventions for their installations, and 
machine room supervisors and operators who will 

Information in the Considerations section is pre- 
sented in these major topics. 

1. General considerations, which apply to all types of 
jobs to be run under control of vsi. 

2. Batch considerations, which apply to "batched" pro- 
duction jobs such as compilation, file maintenance, 
and report generation. 

3. Telecommunication considerations, which apply to 
telecommunications message processing and mes- 
sage switching jobs under vsi. 

4. Graphics considerations, which apply to jobs which 
involve the ibm 2250 or 2260 Graphic Displays. 

5. cpo considerations, which apply to concurrent pe- 
ripheral operations under vsi. 

6. Typical storage configurations. 

7. Operating considerations, which outhne system 
characteristics or actions that are of special interest 
to the machine operator. 



the book. Certain basic definitions, however, are essen- 
tial to understanding the terms as they are introduced. 
These basic definitions are given in the following 
paragraphs. 



Multiprogramming with a Fixed Number of Tasks 

Multiprogramming refers to the concurrent execution 
of several units of work (tasks), any one of which 
would, in a single-program environment, occupy the 
computing system until the task is finished. 

Note: Throughout this publication, job refers to an externally 
specified unit of work (a problem program specified by a JOB 
card), and task refers to any unit of work that must be performed 
by the Central Processing Unit (CPU), under control of a Task 
Control Block (TCB). 

The significance of multiprogramming is that it pro- 
vides increased throughput and better utiHzation of 
resources. A typical task makes use of only a small part 
of the resources available in the system. In a single- 
program environment, this means that overall appHca- 
tion of resources is low. In a multiprogramming envi- 
ronment, however, resource application is markedly 
improved, because the relatively limited demands of 
each of several tasks combine to produce a net demand 
that is more eflBcient in terms of the system's capa- 
bilities. 

The phrase "a fixed number of tasks" indicates that 
the maximum number of tasks the system is capable 
of performing at one time is determined at system 
generation. The number of tasks that can be performed 
at one time can be varied during and after system 
initialization. 



The Use Guide 

The Use Guide consists of self-contained sections, each 
of which provides information on how to modify, ex- 
tend, or implement capabilities of the vsi control pro- 
gram. It is directed to system programmers who have 
the responsibility for maintenance of the system. It is 
assumed that readers of the Use Guide are thoroughly 
familiar with the design of vsi and with its features. 
Although the information in one section is some- 
times related to information in another, or to informa- 
tion in the Planning Guide, all sections are written as 
separate and complete units. This organization has 
been used to reduce cross-referencing and to facihtate 
the addition of new sections. 

Terminology 

Unique terminology is explained as it is presented. 
Additionally, a Glossary is provided in the back of 
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System initialization is the preparation to execute those 
elements of os/vsi that reside in the pageable and non- 
pageable area of virtual storage. This preparation is 
performed by the Nucleus Initialization Program ( nip ) 
when the system is brought into real storage through 
the initial program loading (ipl) procedure, and is 
supplemented by operator action. 



Partitions 

Virtual storage is divided into a pageable area and a 
non-pageable area. The pageable area is further di- 
vided, by the user, into a number of discrete areas 
called partitions. The number of tasks that can execute 
in each partition depends on whether or not the pro- 
grammer has made use of the attach facihty. 

When the attach facility is not used, only one task 
will execute in each partition. The number of parti- 
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tions defined determines the number of tasks that can 
execute concurrently. 

When the attach facility is used, each task can 
attach any number of subtasks (up to a maximum of 
between 196 and 249). Each subtask will then execute 
in the same partition as the attaching task. 

The reason for the variation in the number of attach- 
able sub-tasks involves the use of tcbs (task control 
blocks ) . Each attached sub-task requires a tcb. A max- 
imum of 255 TCBS is available in the system. Of these, 
the system requires a minimum of 5. Also, each active 
partition (or task active in a partition) requires one 
TCB. In a single partition configuration, with minimum 
system options, six tcbs are not available for subtask- 
ing. This reduces the number available for subtasks 
to 249. As more system options and/ or partitions are 
added, additional tcbs are required, up to a maximum 
of 59. This produces the lower limit of 196 available 
for subtasking. 

Each partition has a fixed priority within the system. 
Partition has the highest priority and partition 51 
has the lowest priority. The priority determines which 
partition will gain control of the cpu first when a wait 
condition occurs. 

The small partition, as it is defined under os mft 
(a partition too small to contain the scheduler), does 
not exist in vsi. 



Concurrent Operation 

In a multiprogramming system, tasks are performed 
concurrently. This is a significant programming con- 
cept. Execution is not simultaneous, or overlapped, or 
alternating in a fixed pattern. Each task is contained 



within a partition. The determination of which task 
gains control is based on "waits" and "posts". Waiting 
for an event, such as the completion of an input/ output 
operation, removes the task from contention for con- 
trol. Posting of the task, which signals that the awaited 
event has been completed, causes the task to be placed 
in a "ready" status. The task that becomes active is the 
highest priority task that is ready. This high-priority 
task proceeds until another event causes the task to 
relinquish control. The relinquishing of control by one 
task, and the gaining of control by another task, is 
called task switch. 



Task Switching 

There are two ways in which a task switch can occur: 

1. The active task relinquishes control because it must 
wait for the completion of an event, such as an 
input/ output operation. 

2. Control is seized by a higher-priority ready task as 
a result of an interruption signaling an event for 
which it has been waiting. 

The first case illustrates how multiprogramming en- 
sures optimum utilization of resources. Whenever one 
unit of work cannot proceed, another (highest-priority) 
is advanced. In a single-program environment, no work 
can proceed while the single task waits for an event. 
The second case illustrates how an internal balance 
between the tasks is achieved. When a task has control, 
it retains control only until a task of higher priority be- 
comes ready to proceed. 
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Concepts 



vsi is an ibm System/ 370 Operating System option 
that provides extended multiprogramming capabilities 
and increased flexibility to the Operating System user 
whose system has 128K bytes or more of available real 
storage. 

The system may reside on any of the following devices: 

• IBM 2305-2 Fixed Head Storage Unit 

• IBM 2314 or 2319 Direct Access Storace Facility 

• IBM 3330 Disk Storage 
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Systems with vsi can use the Shared Direct Access 
Storage Device (Shared dasd) feature. This feature 
allows two or more independently-operating comput- 
ing systems to use common direct access storage de- 
vices. VSI can share devices with other configurations 
of the IBM System/ 370 Operating System. 

As many as 15 multi-step jobs can proceed concur- 
rently with the operation of input readers, output writ- 
ers, and as many direct system output writers as there 
are available devices. Each job is associated by job 
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a partition. Partitions are either problem program 
(maximum of 15) or system task partitions with a 
combined maximum of 52 partitions. With jes, readers 
and writers do not run in a partition, and consequently, 
the rdr/wtr classes of os mft are not required in vsi. 
When a iob must wait for completion of an event 

J X. 

such as an input/ output operation, another job of lower 
priority is allowed to proceed. When the higher-prior- 
ity job is ready to resume, the lower-priority job's 
processing is suspended and control of the cpu is re- 
turned to the higher-priority job. The priority of each 
job is determined by the partition in which it resides. 
Jobs are directed to a given partition or group of par- 
titions through the class parameter of the job card. 
By using the class parameter to denote diflFerent 
types of jobs, the user can direct jobs to partitions con- 
sistent with the jobs' characteristics. Process-limited 
jobs, for instance, can be directed to low-priority parti- 
tions so that they do not interfere with eflBcient process- 
ing of jobs that do not require the cpu as often. Tele- 
communications jobs can be directed to higher-priority 
partitions so that the system response time to the termi- 
nal user is minimal. If equal intervals of cpu time are to 
be allotted to certain graphics or other jobs, these jobs 
can be directed to time-slicing partitions (if the time- 
slicing feature is included in the system). If direct 
system output writers are used, the job class of a job 



must be a job class that the writer can process. Direct 
system output writers can handle up to 15 different 
job classes. The class parameter can be used to estab- 
lish which jobs are going to be handled by direct sys- 
tem output writers. Additional applications of the 
CLASS parameter can be established, based on any job 
characteristics meaningful to the installation. 

To use vsi efficiently, both system and application 
programmers must understand how it operates. Be- 
cause other user ^^ersonn x ma^' jpt-oyogt-o/^ i-n o 
summary of vsi operation, without recourse to logic 
descriptions, this section of the publication contains 
these major topics: 

1. Minimum System, Storage and Device Requirements 
describes the minimum system configuration re- 
quired to support VSI. 

2. Devices supported by vsi. 

3. Features and Facilities Hsts the functional capabili- 
ties of vsi and describes each briefly. 

4. Sequence of Operation describes the scheduling, ini- 
tiating and terminating of a series of '■ob*'. 

5. Principles of Operation describes in detail how each 
functional component of vsi operates, and what it 
does. 

Minimum System Storage and 
Device Requirements 

A computing system using vsi must have at least 128K 
uytes oi avaiiaoie reai storage aiiu tne lOiiowiiig ue- 
vices and features: 

• Dynamic Address Translation (dat) 

• Standard multiplexor channel wdth associated in- 
put/output devices 

• One selector and/ or block multiplexor channel with 
associated input/ output devices including an ibm 
2314/2319 Direct Access Storage Facility, or an 
IBM 3330 Disk Storage, or an ibm 3333 Disk Storage 
and Control 

• Storage protection 

• Program event recording 

• Monitor call 

The system configuration must include at least three 
IBM 2314/2319 disk drives or two ibm 3330 disk drives. 

If the shared direct access device feature is selected, 
the system must also include one ibm 2314 combined 
with a 2844 Auxiliary Storage Control Unit, or one of 
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a two-channel Printers 



the following units equipped with 
switch: 

• IBM 2305-2 Fixed Head Storage Unit 

• IBM 2314/2319 Direct Access Storage Facility 

• IBM 3330 Disk Storage 
or 

• a 4-channel switch with the ibm 3330 Disk Storage 

• a 4-channel switch with the ibm 3333 Disk Storage 
and Control 

Devices Supported by VS 7 

vsi provides support for the following hardware de- 
vices: 

CPUs 



IBM Model 


135 


Processing Unit 


Model 
Model 
Model 


145 

1551] 

158 


Processing Unit 
Processing Unit 
Processing Unit 


DASD 






IBM 2305-2 


Fixed Head File 


2314 


Disk 


2319 


Disk 


2835-2 


Control Unit 


2844 


Control Unit 


3330 


Disk 


3333 


Disk Storage and Control 


3830-1, 


-2 Control Unit 


Integrated File Adapter for Models 135 a 


Tape 






IBM 2401/2/3/4 


Tape 


2415 
2420 
2495 




Tape 
Tape 
Tape Cartridge Reader 


2671 
2803 




Paper Tape Reader 
Control Unit 


2804 




Control Unit 


2816 




Tape Switch 


2822 
3410 
3411 
3420 
3803 




Paper Tape Control Unit 

Tape 

Tape 

Tape 

Control Unit 


MICR/OCR 




IBM 1275 


OCR 




1287 


OCR 




1288 


OCR 




1419 


MICR (PCI adaptor required) 


Displays/ Consoles 


IBM 1052-7 




Console 


2150 




Console 


2250-1, 
2260-1, 
2265 
2840 


-3 
-2 


Display /Console 
Display/ Keyboa rS 
Display 
Control Unit 


2845 




Control Unit 


2848 




Control Unit 


3210 




Console 


3213 




Console Printer 


3215 




Console 



IBM 1403-Nl, 2, 
1404-2 
1443-Nl 
2821 

3211-1, -2 
3811 



3, 7 Printer 

Printer (1403 support only) 

Printer 

Control Unit 

Printer 

Control Unit 



Integrated Printer Adapter for Model 135 



Reader /Punch 

IBM 1442-Nl, 2 
2501 
2520 
2540 
2596 
2821 
3505 
3525 



Reader/Punch 

Reader 

Reader/Punch 

Reader/Punch 

96 Column Reader (1442 support only) 

Control Unit 

Reader 

Punch 



Display Console (for Model 3158) 



Transmission Control Unit 

IBM 2701 Transmission Control Unit 

2702 Transmission Control Unit 

2703 Transmission Control Unit 
2715 Transmission Control Unit 
2772 Multi-purpose Control Unit 
2955 Data Adapter Unit 

I 3705 Communications Controller 

7770 Audio Response Unit 
Integrated Communications Adapter for Model 135 

Start /Stop Terminals 

IBM 1030 Data Collection System 

1050 Data Collection System 

1060 Data Collection System 

2721 Portable Audio Terminal 

2740 Communication Terminal (Models 1 & 2) 

2741 Communication Terminal (Model 1) 
2760 Optical Image Unit 

ATT 83B3 ATT Terminal 

WU 115A Teletype 

World Trade Telegraph Terminals 

TWX 33/35 ATT Teletype Terminal 

IBM System/7 Processor Station 

Binary Synchronous Terminals 

IBM 1130 Processor Station 
1800 Processor Station 
2770 Data Communications System 
2780 Data Transmission Terminal 
2790 Data Communications System 
2972-8, -11 General Banking Station 
System/3 Processor Station 
System/360 Processor Station 
System/360, Model 20 Processor Station 
System /370 Processor Station 
I 3270 Information Display System 

3735 Programmable Buffered Terminal 

Console device support provided in vsi is sum- 
marized in Figure 1. scs represents Single Console 
Support and mcs represents Multiple Console Sup- 
port. The numbers in parentheses under mcs indicate 
the maximum number of devices supported. Blank 
spaces indicate no support as a system console. 
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■ Console 
: Type 


System Support 


System Console Support 


SOS 


MCS 


MCS+DIDOCS ' 


= 3215 


X (current 1052) 


X 


X(32) 


X(32) -, 


-•■ 3210 


X (current 1052) 


X 


X(32) 


X(32) : 


; 3213 


X (current 1052) 








1403 


X 


X 


X(32) 


X(32) 


* 3211 


X 








; 2501 


X 








I 2520 


X 






I 


I 2540 


X 


X 


X(32) 


X(32) I 


." 3505 


X 


X 


X(32) 


X(32) : 


W 2250 


X 






MOD 1,3 
X(32) 


■ 2260 


X 






MOD 1 X(32) 


\ 3277 


X 






X(32) 


1 3158* 


X 


X 


X(1) 


X(1) t 


^ 2740 


X (via BTAM) 




X(32) 


X(32) 



* Display Console for Model 158 Processing Unit 
Figure 1. VSl Console Device Support 

Features and Facilities 

VSl makes possible the concurrent execution of up 
to 15 separate jobs within a single computing system 
ha\dng only one central processor, while continuing to 
provide all other applicable services of the ibm Sys- 
tem/370 Operating System. Other features of vsi in- 
clude: 

• Automated Initialization. 

• Virtual Storage ( up to 16,777,216 bytes ) . 

• Independent job scheduling. 

• Virtual=real execution facility. 

• System Management Facilities ( smf ) . 

• Job/ step CPU timing. 

• Job step CPU time limiting. 

• WAIT time limiting. 

• Checkpoint/ restart. 

• Recovery Management Support 

• Redefinition of partition sizes and characteristics 
during operation. 

• System input readers. 

• Reading of an input stream from an ibm 2314, 2319, 
3330, or tape. 

• System output writers. 

• Direct system output writers. 

• Restarting the system without losing enqueued jobs. 

• Concurrent execution of tasks within a partition. 

• Remote Entry Services ( res ) 



Some of the features are described briefly in the 
following paragraphs and explained in detail under 
the heading Principles of Operation. 



Automated Initialization 

This feature, when used, makes the initialization pro- 
cess more rapid and flexible. It can reduce the operator's 
role in the process to a single entry on the console. 
Flexibility comes from the use of the sysi.parmlib data 
set (or card reader) to hold members (or control 
cards) that contain the system initialization param- 
eters. By proper definition of the parameters, each 
initialization tailors the system to better meet the needs 
of the anticipated job mixture. 

Before initialization, a system programmer enters 
the needed parameters in sysi.parmlib members by 
using the iebupdte utility. During initialization, the 
nucleus initialization program (nip) requests the op- 
erator to "specify system and/ or set parameters". 
To use automated initialization, the operator simply 
enters (via the console) a reference to the list of 
sysi.parmlib members to be used. The list of members 
may itself be a member of sysi.parmlib, or it may be 

- 3 J_„1. T„ j-U.* j-l-_ J. ' 1„ : J 1 
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to a brief response to a system message. 

This implementation enables much more rapid ini- 
tializations than others, which involve the operator's 
manually entering all the needed parameters via the 
console. Automated system initialization may be in- 
voked at the user's convenience. That is, unless the 
operator uses the new keywords for automated system 
initialization, the manual entry procedure must be 
followed. This feature requires no changes in the sys- 
tem generation options, but the implementation of 
automatic start commands is slightly changed. Its use is 
more fully described in the Use portion of this guide 
under the heading Automated System Initialization. 



Extended Multiprogramming Capabilities 

VSl permits 15 problem program jobs to operate 
concurrently in the system. Jobs are scheduled into 
partitions through use of the class parameter on the 
job statement, in conjunction with the prty parameter. 
The class parameter may designate one of the 15 avail- 
able job classes, A-O. With the storage protection and 
fetch protection features, each of these jobs is pro- 
tected from damage by other jobs, and the system 
areas are protected from all problem programs. 
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Independent Job Scheduling 

All partitions are independent with respect to job 
scheduling and initiation. Jobs are scheduled into the 
first available problem program partition that services 
the corresponding job class. Jobs are initiated accord- 
ing to the PRTY parameter on their job cards. 

Virtual = Real Execution Facility 

The Virtual=Real execution facility permits the user 
to have real storage available for any of his programs 
that will not run in the normally paged environment 
of vsi. Real storage will be allocated, at job execution 
time, with real storage addresses equivalent to virtual 
storage addresses on a byte basis, for the equivalent 
amount of virtual storage he has defined for the job 
involved. Multiple virtual=real jobs can execute con- 
currently if enough real storage is available in the sys- 
tem to accommodate the jobs. Programs that will not 
run in a paged environment are identified, and the 
facility is discussed in more detail, in this section of 
the publication under the heading Virtual=Real Ex- 
ecution. 



System Management Facilities (SMF) 

SMF is Optional with vsi. smf collects and, optionally, 
records system, job management, and data manage- 
ment information, and provides control program exits 
to installation-supplied routines that can periodically 
monitor the operation of a job or job step. 



Job/Step CPU Timing 

Job/ step CPU timing is a standard smf feature with 
VSI. The amount of time that each job or job step 
has control of the cru is calculated by task manage- 
ment routines. If smf=basic is selected, this value is 
passed to the user-suppHed accounting routine if one 
is provided; if smf=fulx, is selected, the value is passed 
to the SMF user exit routines as provided. 

Job Step CPU Time Limiting 

This feature allows the user to specify the maximum 
amount of time that a job step can use the cpu. How- 
ever, if the SMF option is selected and a user exit 
routine is provided, this routine can extend the time 
limit so that processing can continue. 



the installation can determine the time limit by pro- 
viding a user exit routine that can extend the time 
limit. 



Checkpoint/Restart 

The checkpoint/ restart facility provides an opportu- 
nity to restart a job that terminates abnormally due to 
a hardware, programming, or system error. The restart 
is permitted either at the beginning of a job step or 
at a checkpoint within a job step. In either case, the 
restart may be automatic or may be deferred until the 
job is resubmitted. 

Recovery Management Support 

Recovery management is a service provided in vsi that 
overcomes the damaging effects that a computer, chan- 
nel, or i/o device malfunction might otherwise have on 
a program in progress. 

Partition Redefinition 

With the facility of partition redefinition, virtual stor- 
age can be reconfigured during system initiahzation 
or during operation, provided that the partitions to be 
redefined are contiguous. The partitions will quiesce 
automatically and require no intervention beyond the 
DEFINE command. The number of partitions in the sys- 
tem can be decreased, or increased within the limits 
established at system generation (sysgen). Partition 
attributes may be changed also, including the job 
class (es), sizes of the partitions, identification, de- 
activation/ reactivation characteristics, and time-slicing 
attributes. 



System input Readers 

System input readers, as they exist in os mft, do 
not exist in vsi. Instead, the Job Entry Subsystem 
(jEs), residing in its own area of virtual storage, 
processes all system input, reading and spooling the 
input to the appropriate data sets, jes accepts job con- 
trol language statements and data in the input stream, 
including multiple data sets for the same job step, and 
transcribes that data onto a direct access device for 
retrieval by the problem program. An input job stream 
on cards is illustrated in Figure 2. Input to jes from 
tape or disk can be blocked. 



Wait Time Limiting 

This feature suspends processing of a job step if the 
job step remains in a wait state for more than an 
established time limit. If the smf option is selected, 



Input Stream from Disk 

vsi allows the user to establish a disk storage drive 
(iBM 2314, 2319, or 3330) as a system input device. 
Data in the input stream is permitted, including mul- 
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Figure 2. Input Job Stream 



tiple data sets for the same job step, providing the 
facility for: 

1. Reading input from sequentially organized data 
sets. 

2. Deblocking of blocked input records. 

3. Automatically switching volumes if end-of-volume 
is detected on a data set extending across volumes, 
or if concatenated data sets are being processed. 

4. Starting more than one reader for the same disk 
storage unit. 

System Output Writers 

System output writers, resident in partitions as they 
are in os mft, do not exist in vsi. Instead, system out- 
put, with the exception of direct system output, is 
written by jes output writer(s), resident in the page- 
able supervisor area of virtual storage. Each output 
writer can handle as many as eight different output 
classes. More than one writer can service the same 
output class. 



Direct System Output Writers 

Direct system output writers are a job scheduler func- 
tion. They enable a job's output data sets to be written 
directly to an output device during execution of the 
job. 

Direct system output writers operate in problem 
program partitions. As many writers can operate in a 
partition as there are devices available. Each writer 
must be assigned to only one device and can process 
one system output class. Problem program output can 
be handled by a direct system output writer if the job 
class of the problem program is an eligible job class 
and the problem program is executing in the same 
partition as the writer. 



System Restart 

It is sometimes necessary to shut down the system 
while needed information still exists on the job queue 
data set (sysi.sysjobqe). Such occasions might be 
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end-of-shift, end-of-day, scheduled maintenance, sys- 
tem malfunction, or power failure. System restart per- 
mits all enqueued input and output jobs that had 
been entered in the job queue to remain there for 
subsequent retrieval by the system. Jobs that were 
being processed at the time of shutdown must be re- 
started. 



VS1 Subtasking 

vsi allows the user to have any number of tasks (up 
to a maximum of between 196 and 249 ) executed con- 
currently within a partition. This feature provides the 
user with: 

• An ATTACH function that can create subtasks. 

• A DETACH function that removes completed tasks 
requested by the attach routine. 

• A chap function that allows a problem program to 
change dispatching priorities of the tasks within the 
partition. 



Remote Entry Services (RES) 

Remote entry services (res) is an extension of p;s and 
provides the remote terminal (work station) users 
with the same batch computing facilities that are 
available at the central installation. It allows jobs to 
be submitted from a work station and output to be 
routed back to the same work station and/ or to other 
work stations. Besides accepting job input and routing 
output, RES facilities provide for sending messages be- 
tween users and showing job, terminal, or work station 
status. 

RES support consists of: 

• Additions to existing jes components 

• Modifications to the command processor for the 
commands listbc, logon, logoff, route, and send 

• The RES data sets sysi.uads and sysi.brodcast 

• The Remote Terminal Access Method ( rtam ) 

• Extensions to wto and wtor functions 

• IKJRBBMP — a new standard utility used to create 
and build sysi.uads and sysi.brodcast. 

Except for rtam, all changes to vsi to support res 
are always in the system, sysi.uads and sysi.brodcast 
are required if remote users are to use the system. 
sysi.uads is also required if the central operator logon/ 
logoff function is to be used. Otherwise, these data 
sets may or may not be specified (if present, they are 
used). 

RTAM is the only part of the res package that is not 
present in any way in the system unless it is specifically 
included by a separate rtam system generation. It is 
the only teleprocessing access method used by res. 
RTAM resolves all work station, communication line, 



and transmission code dependencies. It is started on a 
communication line basis rather than on a terminal/ 
work station basis. 

To initiate processing, the central operator issues 
a START RTAM Command, which, in turn, starts one or 
more communications lines. Additional lines may be 
started later by entering a modify command specifying 
lines previously allocated to rtam. 

The priority of a job read in from a remote user may 
be determined by the qid entry built at ipl time. The 
gro table is built from the sysi.uads data set. 

Jobs entered from remote work stations are placed 
on the system input queues. However, for each remote 
user, there are 36 output queues ( classes A-Z and 0-9 ) 
and 1 output hold queue in addition to the system 
output and hold queues. This, of course, requires addi- 
tional space on the job queue data set (sysi.sysjobqe). 

For details on res and rtam, including machine and 
additional space requirements, see the os/vsi res 
System Programmer's Guide, GC28-6878. 

Sequence of Operation 

To illustrate the concepts of vsi, a sample sequence 
of operation is described here. (For an overview of 
the processing performed by various components of 
the control program, refer to Appendix A.) 

In the job stream shown in Figure 2, the following 
class parameters appear on the job cards: 

1. CLASS=N 

2. CLASS=D 

3. CLASS=L 

4. CLASS=J 

5. class=m 

6. class=c 

7. None 

8. CLASS=J,PRTY=12 

9. CLASS=C 

The system is loaded by use of the normal ipl pro- 
cedure and initializes itself by use of the nucleus 
initialization program ( Figure 3 ) . After system initiali- 
zation, the contents of virtual storage are as shown in 
Figure 4. The job class identifiers assigned to each 
partition at system generation are the alphabetic char- 
acters shown in the upper right comer of the parti- 
tions. Partitions and 1 are shown as not active. Fig- 
ure 5 illustrates the input work queues established at 
system initialization. When a start command is en- 
tered for the reader, the reader begins reading the 
job stream and entering jobs into the input work 
queues for each class (Figure 6). The start com- 
mands for the initiator and writer are also entered. 

The initiator in P4 now schedules the first job 
(Figure 7). Because n is the primary job class as- 
signed to P4, the initiator searches the class=x queue 
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Figure 3. Contents of Virtual Storage after Nucleus Initialization 
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Figure 4. Contents of Virtual Storage after System Initialization 
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Figure 5. Input Work Queue after System Initialization 
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Figure 6. Input Work Queues after First Three Jobs Have Been Entered 
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Figure 7. Contents of Virtual Storage after START Commands 
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first ( job 1 has been placed on the queue by this time ) , 
and job 1 is initiated and given control (Figure 8). 
The reader continues reading the input stream, plac- 
ing jobs in their appropriate queues. As soon as a job 
is completely read in, it may be scheduled if a partition 
servicing the particular job class is available. Job 3 will 
be scheduled into P2 ( because L is the secondary class 
for P2 ) and job 4 will be scheduled into P3 ( because J 
is the secondary class) when they have been read in. 
Because job 7 has no class parameter, it is placed on 
input work queue A ( the default job class ) . Job 8, with 
a PRTY parameter specifying priority 12, would be 



placed on input queue J ahead of job 4 if job 4 had not 
already been scheduled. At this point jobs 1 through 
9 have been read and placed on their appropriate 
queues (Figure 9). 

When job 1 has finished processing, a scheduler is 
brought into P4 to terminate the job. The scheduler 
now searches input work queue n for a job for P4. 
Because the class=n queue is empty, the class=c 
queue is searched. Job 6 is waiting on the queue; there- 
fore, it is scheduled into P4. At this point, the contents 
of virtual storage are as shown in Figure 10. 











Figure 8. Contents of Virtual Storage after First Job has been Scheduled 
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Figure 9. Input Work Queues after All Nine Jobs Have Been Entered 







Nucteus 



System 
Queue 



Job6 
Running 



Job4 
Running 



64K 






[\ 



Jobs 

Running 

64K 




64K 



64 K 



Pageable 
Supervisor 

and JtS !''T|S 









Figure 10. Contents of Virtual Storage with Three Partitions Active 
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Principles of Operation 

This topic describes the principles of operation of 
vsi. Included are: 

• Partition job class facility. 

• Priority within job class. 

• Job/ step CPU timing 

• Virtual storage organization. 

• Checkpoint/ restart. 

• Partition redefinition. 

• System input readers. 

• Scheduling process. 

• System output writers. 

• Direct system output writers. 

• System restart. 

Figure 11 illustrates a configuration referred to 
throughout the remaining discussion of Principles of 
Operation. P/P denotes problem program partition. 

Partition Job Class Facility 

The partition job class facility allows one or more 
partitions to be assigned to selected jobs. During sys- 
tem generation, a partition must be assigned to service 
each job class that will be used. These assignments 
may be modified later. (See Partition Redefinition in 
this section.) Each problem program partition may 
be assigned as many as 15 job classes designated by 
the alphabetic characters A through O. These job class 
designations have no inherent meaning; they can be 
used to denote any job characteristic, which would in- 
fluence the choice of partitions for the job, meaningful 
to the installation. More than one partition may be as- 
signed to service the same job class (es). In Figure 11, 
P3 is assigned to job classes C, J, and A; P4 is as- 
signed to N, C, and D. These partition job class 
identifiers are used by the system to determine which 
input queue is searched first by an initiator servicing 
a specific partition. (See Problem Program Partitions 
in this section.) The sequence in which jobs are se- 
lected from each input work queue is determined by 
the PRTY parameter, (See Enqueuing Jobs by class 
and PRTY in this section. ) 



The partition(s) in which a job executes is con- 
trolled by using the class parameter on the job state- 
ment. The format of this keyword parameter is : 

CLASS = job class 

where job class is the alphabetic identifier (A-0) as- 
signed to the job. If this parameter is omitted from 
the JOB card, a job class of A is assigned by the sys- 
tem. All 15 job classes may be used, provided at 
least one partition has been assigned to each of the 
classes specified. When a job class for a particular 
job is designated (by the class parameter), the job is 
executed only in a partition that has been assigned to 
service that class. If more than one partition is as- 
signed to service that job class, the job is executed in 
the first available problem program partition. A typi- 
cal JOB card may be specified as follows: 

//JOBPAY JOB 661,7DOE',CLASS = C,PRTY = 12 

In the configuration illustrated in Figure 11, this 
JOB card causes the job to execute in either P3 or P4, 
whichever is available first. 



System Management Facilities 

SMF is included at system generation by specifying 
SMF= in the schedule macro instruction. ( This param- 
eter replaces acctrtn= in os mft.) There are three 
options for smf: 
smf=notsupplied — specifies that the user does not 

want any smf processing. 
SMF=BASic — specifies that user-v/ritten accounting rou- 
tines are being provided, jes accounting informa- 
tion and two additional exits are also provided, 
SMF=FULL — specifies that the full system management 
facilities routines are to be provided, vsi provides 
two additional exits and additional jes accounting 
information. 

The collected information is written onto data sets 
on direct access devices. 




Figure 11. Sample Five-Partition Configuration 
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Job/Step CPU Timing 

Job/ step CPU timing is a standard smf feature in vsi. 
CPU timings are calculated for each job step. This 
value is then passed, along with an accumulated value 
for the entire job, to a user-supplied accounting rou- 
tine for further processing. 

Note: The CPU timings include only the active time that the 
CPU has control of the job step. It does not include the wait 
time or the time used by the initiator and terminator for that job. 



Functions of the Control Program with VSI 

The control program routines of vsi have four major 
functions: job management, task management, data 
management, and recovery management. 



Job Management 

Job management is the processing of communications 
from the programmer and operator to the control pro- 
gram. There are two types of communications: 

1. Operator commands, which start, stop, and modify 
the processing of jobs in the system. 

2. Job control statements, which define work being 
entered into the system. 

Processing of these commands and statements is re- 
ferred to as command processing and job processing, 
respectively. 



Task Management 

Task management routines monitor and control the 
entire operating system, and are used throughout the 
operation of both the control and processing programs. 
Task management has seven major functions: 

• Interruption supervision. 

• Task supervision. 

• Virtual storage supervision. 

• Page supervision. 

• Contents supervision. 

• Overlay supervision. 

• Timer supervision. 

The task management routines are collectively re- 
ferred to as the "supervisor." 



Data Management 

Data management routines control all operations asso- 
ciated with input/ output devices: allocating space on 
volumes, channel scheduling, storing, naming, and 
cataloging data sets, moving data between real and 
auxiliary storage, and handling errors that occur dur- 



ing input/ output operations. Data management rou- 
tines are used by processing programs and control 
program routines that require data movement. Process- 
ing programs use data management routines primarily 
to read and write required data, and also to locate 
input data sets and to reserve auxiliary storage space 
for output data sets of the processing program. 
Data management routines are: 

• Input/ output (i/o) supervisor, which supervises 
input/ output requests and interruptions. 

• Access methods, which communicate with the i/o 
supervisor. 

• Catalog inaoageuienL, which maintains the catalog 
and locates data sets on auxiliary storage. 

• Direct access device space management (dadsm), 
which allocates auxiliary storage space. 

• Open/ close/ end-of- volume, which performs re- 
quired initialization for i/o operations and handles 
end-of -volume conditions. 

The Virtual Storage Access Method, vsam, is an- 
nounced but not available, vsam is an access method 
for use with direct access storage devices on IBM Sys- 
tem/370 with vs. VSAM creates and maintains two types 
of data sets. One is sequenced by a key field within 
each record and is called a key-sequenced data set. 
Data records are located by using the key field and an 
index that records each key field and the address of the 
associated data, similar to isam. The other is sequenced 
by the time of arrival of each record into the data set 
and is called an event-sequenced data set. Data records 
are located by using the records displacement from 
the beginning of the data set. The displacement is 
called the relative byte address ( rba ) . The rba is simi- 
lar to the relative block address used with bdam. 

VSAM stores, retrieves, and updates user data records 
in these types of device-independent data sets, vsam 
stores data records in a new data format designed for 
long term data stability and for data base applications. 
Data in both types of data sets can be accessed either 
sequentially or directly. 

VSAM enhances many isam capabilities including 
device independence, concurrent processing, and the 
kinds of accessing supported. It provides additional 
password security protection, vsam creates and main- 
tains separate vsam catalogs that contain specialized in- 
formation about each vsam data set and are used to link 
a data set with its index, vsam includes a multifunction 
utility program that will define, delete, print, copy, and 
provide backup and portability of vsam data sets and 
maintain the separate catalogs. An interface routine to 
allow most isam programs access to vsam data sets is 
also provided. For a more detailed explanation of 
vsam, see the OS/VS Virtual Storage Access Method 
Planning Guide, GC26-3799. 
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Recovery Management 

Recovery management services are provided through 
the following programs: 

Machine-Check Handler: This program processes 
machine-check interruptions. Depending on the sever- 
ity of the malfunction, the machine-check handler ( 1 ) 
restores the system to normal operation, (2) termi- 
nates tasks associated with the malfunction so the sys- 
tem can resume processing, or (3) places the system 
in a wait state. In all cases, the machine-check handler 
program writes diagnostic messages and error records. 

Channel-Check Handler: This program receives con- 
trol after the detection of a channel data check, chan- 
nel control check, or interface control check. For chan- 
nel control checks and interface control checks, cch: 

• Indicates the results of the analysis of the error for 
later use by the error recovery procedures when 
they set up for a retry of the i/o operation. 

• Constructs a record of the error environment. When 
this record is later recorded, a message is issued to 
inform the operator that a channel-detected error 
has been recorded on logrec. 

For channel data checks, cch constructs a record of 

Liie. oiioi. X no (Jiiux icv-Ovciy L/iucciauxca uu nut rcuuiit: 

information from cch to retry i/o operations on which 
channel data checks occurred. 

Dynamic Device Reconfiguration: This program, 
upon receiving a request from the operating system 
or from the operator, permits a demountable volume 
to be moved from one device to another and reposi- 
tioned if necessa"'. This method is used to bvpass vari- 
ous i/o errors, and is done without abnormally termi- 
nating the afiFected job or reperforming an initial 
program load (ipl). 

Alternate Path Retry: This program allows an i/o 
operation that has developed an error on one channel 
path to be retried on another channel path, if another 
channel path is assigned to the device performing the 
i/o operation. Alternate path retry also provides the 
capability to vary a path to a device online or ofiFline. 

Missing Interruption Checker (MIC): This program 
polls active i/o operations to determine if a channel 
end and/ or device end interruption has been pending 
for more than an installation-specified period of time. 
Also, it provides a reminder message for mount re- 
(juests. For more detailed information, see the Fea- 
tures and Options (FEA) section in the Use portion of 
this manual. 



Control Program Organization 

The control program is on auxiliary storage in three 
partitioned data sets created when the system is gen- 
erated. These data sets are: 

• The NUCLEUS partitioned data set (sysi. nucleus), 
which contains the Nucleus Initialization Program 
(nip) and the resident portion of the control pro- 
gram. 

• The svcLiB partitioned data set (sysi.svclib), which 
contains nonresident svc routines, nonresident error- 
handling routines, and the access methods routines. 

• The linklib partitioned data set (sysi.linklib), 
which contains other nonresident control program 
routines and iBM-supplied processing programs. 



Resident Portion of the Control Program 

The resident portion ( nucleus ) of the control program 
is in SYSi. NUCLEUS. It is made up of those routines, con- 
trol blocks, and tables that are brought into storage at 
initial program loading (ipl) and are never overlaid 
by another part of the operating system. The nucleus 
is loaded into the non-pageable area of virtual storage. 
The resident task management routines include: 

• Interrupt supervision. 

• V irtuSi storage supervision. 

• Page supervision. 

• Timer supervision. 

They also include portions of the routines that per- 
form: 

• Task suDcrvision. 

i. 

• Contents supervision. 

• Overlay supervision. 

The resident job management routines are those rou- 
tines of the communications task that receive com- 
mands from the operator, and the master scheduler 
task. 

Communications Task: The communications task 
processes the following types of communication be- 
tween the operator and the system: 

• Operator commands, issued through a console. 

• Write-to-operator (wto) and write-to-operator with 
reply (wtor) macro instructions. 

• Interruptions caused when the interrupt key is 
pressed, to switch from the primary console to an 
alternate console. 

Master Scheduler Task: The master scheduler task 
processes job queue manipulation commands and par- 
tition definition. For example, a hold or define com- 
mand is processed by the master scheduler task. 

Concepts 23 



t^ii o-JAS., 







Figure 12. Virtual Storage Organization 



The resident data management routines are the 
input/ output supervisor and the bldl routines of the 
partitioned access method. 

Optionally, other access method routines may be 
made resident. 

The user may also select resident reenterable rou- 
tines, which are access method routines from sysi.svclib, 
and other reenterable routines from sysi.linklib. At 
system generation, the user specifies that he wants such 
routines resident in virtual storage. At ipl, he identi- 
fies the specific routines desired in the RAM=entry. The 
selected routines are loaded during system initializa- 
tion and reside in the high end of virtual storage (see 
Figure 12). The resident bldl table is standard. It 
contains directory entries for selected modules from 
the linkage or svc hbraries. 

Normally transient svc routines ( that is, types 3 and 
4 svc routines ) can be made resident through the rsvc 
option, specified by the user, nip loads these routines 
adjacent to the resident reenterable routines. If there 
are no resident reenterable routines, the routines are 
loaded adjacent to the transient areas. ( See Figure 12.) 

Nonresident Porfion of the Control Program 

The nonresident portion of the control program com- 
prises routines that are loaded into virtual storage as 

tliev are needed, sad. wlilel.i. can he overlaid after their 



completion. The nonresident routines operate from the 
partitions and from two sections of the pageable super- 
visor area called transient areas. 

The non-resident routines which perform job man- 
agement are collectively referred to as the scheduler. 

Virtual Storage Organization 

In a single task environment, virtual storage is divided 
into two areas: the non-pageable area, and the page- 
able area. In multiprogramming with a fixed number 
of tasks, the pageable area is divided further into as 
many as 52 discrete areas called partitions. Figure 12 
shows the division of virtual storage. 

The non-pageable area, located in the lower portion 
of virtual storage, contains the resident portion of the 
control program, and control blocks and tables used by 
the system. The size of the non-pageable area depends 
on the number of partitions established by the user, 
and the control program options selected at system 
generation. 

The vsi system nucleus occupies an area containing 
at least 54K bytes in virtual storage. 

Partitions are defined within the pageable area, lo- 
cated in the upper portion of virtual storage, at system 
generation, The number of partitions may be varied 
within the number specified at system generation, and 
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the sizes and job classes of partitions may be rede- 
fined at system initialization or during operation. Each 
partition may be occupied by a processing program, or 
by control program routines that prepare job steps for 
execution (job management routines), or that handle 
data for a processing program (access method routines). 
Provided the total number of partitions does not 
exceed 52 and enough computing system resources are 
available, vsi provides for the concurrent execution 
of as many as 15 problem programs. Each program 
is located in its own partition of virtual storage, with 
input readers and output writers, under control of jes, 
being located in the jes portion of the pageable super- 
visor area. The vsi system provides for task switching 
among the tasks in the partitions, and between those 
tasks and the communications task and master sched- 
uler task in the system area. 



Non-pageable Area 

The non-pageable area is that part of virtual storage 
into which the nucleus and sqa is loaded at ipl. The 
storage protection key of the non-pageable area is zero 
so that its contents can be modified by the control 
program only. 

System Queue Area: The system queue area is lo- 
cated in the resident super\isor area of \'irtual storage. 
As SQA is needed, it is extended dynamically in both 
real and virtual storage. It contains enq/deq control 
blocks and command scheduling control blocks (cscbs). 
In addition, if the communications task cannot obtain 
WTO buffer space, sqa is used. 

The size of the s'^^'stem queue area is initially estab- 
lished at system generation ( via the sysque parameter 
of the CTRLPROG macro instruction ) . It can be modified 
at IPL time. 

The system queue area also contains task related 
control blocks for each active subtask. In this case, 
the size of the system queue area is determined by: 
the number of partitions, and the number of subtasks 
that can be concurrently active. The size of the sys- 
tem queue area, established during system generation, 
should be retained. 

The system queue area (sqa) is established by nip 
adjacent to the fixed area and provides the virtual stor- 
age space required for tables and queues built by the 
control program. The sqa must be at least 4K bytes for 
a minimum one-partition system. Its storage protection 
key is zero so that it can be modified by control pro- 
gram routines only. Data in the system queue area 
indicates the status of all tasks. 



Pageable Area 

Figure 13 shows how the contents of each partition in 
the pageable area are organized and how they are 
related to the rest of virtual storage. Routines are 
brought into the high or low portion of a vsi par- 
tition. Job management routines, processing programs, 
and routines brought into storage via a link, attach, 
or XCTL macro instruction, are loaded at the lowest 
available address. The highest portion of the partition 
is occupied by the user parameter area and user save 
area. The next portion of the partition is occupied by 
the task input/ output table (tiot), which is built by 
a job management routine (i/o device allocation rou- 
tine). This table is used by data management routines 
and contains information about dd statements. 

Each partition may be used for a problem program 
as well as for system tasks. When the control program 
requires virtual storage to build control blocks or work 
areas, it obtains this space from the partition of the 
processing program that requested the space. Access 
method routines and routines brought into storage via 
a LOAD macro instruction are placed in the highest 
available locations below the task input/ output table. 

Working storage and data areas are assigned from 
the highest available storage in a partition. 

The high portion of the pageable area is occupied by 
the pageable supervisor routines, the dump area, page- 
able SQA, the jes routines, and it also contains two 
transient areas into which certain nonresident routines 
are loaded when needed: the svc transient area (2048 
bytes) and the i/o supervisor transient area (1024 
bytes). These areas are used by nonresident svc rou- 
tines and nonresident i/o error-handling routines, re- 
spectively, which are read from sysi.svclib. 

Each transient area contains only one routine at a 
time. When a nonresident svc or error-handling rou- 
tine is required, it is read into the appropriate tran- 
sient area. The transient area routines operate with a 
protection key of zero, as do other routines in this area. 

System Input Readers 

System input readers, resident in partitions as they 
exist in os met, do not exist in vsi. Instead, system in- 
put is handled by the jes reader(s), resident in the 
pageable supervisor area of storage. For additional 
information concerning the jes reader, see the explana- 
tion under the heading Input Readers in this section. 

Problem Program Partitions 

vsi permits up to 15 partitions to be specified for prob- 
lem programs. Each partition may have up to 15 job 
class identifiers; more than one partition may be as- 
signed to service the same job class (es). Problem pro- 
gram partitions must be at least 64K in virtual size. 
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Figure 13. Division of Virtual Storage 



Problem programs run concurrently with system 
readers and writers. When a problem program in a 
partition is terminated, a scheduler is brought into that 
partition to retrieve another job from the input work 
queue for the appropriate job class (es). Control is then 
given to the appropriate task; for example, if a problem 
program is retrieved from an input queue, control is 
given to the program for execution. 
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For example, in Figure 11, P4 is assigned job classes 
N, C, and D. If a job of class N has just been termi- 
nated, the initiator first searches the job class N input 
work queue. If no class N jobs exist, the initiator 
searches for job class C jobs; if no class C jobs exist, 
the job class D input queue is searched. If all three 
queues are empty, the partition remains dormant until 
r:^'-^ Vqt -;ob w^Kn c'n'^" N. C, or D is read into the svs- 



System Task Partitions 

Up to 37 system task partitions are available in vsi. 
They are specified as system task partitions, by the 
user, by the c-s parameter of the partitns macro in- 
struction. They may be used in vsi to ensure that par- 
titions are available to: 

• Start and stop readers and writers. 

• Process mount procedures. 

• Run conversational remote job entry readers. 

• Run the generalized trace facility. 

System task partitions are not required to run readers 
and writers in vsi as they were in os/mft. Readers and 
writers in vsi ( other than direct system output writers ) 
operate from the pageable supervisor area of storage. 

Virtual=Real Execution 

Real storage in vsi consists of a non-pageable section 
and a pageable section. The resident supervisor, includ- 
ing the nucleus and the system queue area occupy the 
non-pageable area. The pageable area is occupied by 
pages of programs (user's and systems) which are 
brought into it for execution and are then returned to 
auxiliary storage. This is referred to as a paged en- 
vironment. 

Two types of programs exist that cannot run in a 
paged environment: 

1. Excp programs that modify the channel program 
while it is active, such as oltep. 

2. Programs that are highly time-dependent, such as 
1419 programs. 

To permit these programs to operate under vsi, a 
facility is provided that permits the user to specify how 
much real storage he wants available for his programs 
in a non-paged environment. He does this by specify- 
ing ADDRSPC=REAL and KEGiON=nnnK, where imnK is 
equal to the real storage required for his job, on the 
JOB or EXEC JCL statement. Storage will be allocated 
based on the region= parameter or, if region= is 
omitted, on the specification in his reader procedure. 
Storage will be allocated at job execution time as 
needed. Virtual addresses will still be processed by the 
dynamic address translation feature, but page tables 
will be built so that the translated addresses are the 



same as the untranslated addresses. Figure 14 shows 
the contents of virtual storage in a virtual=real situa- 
tion. The problem program in partition 2 requires 
virtual=real storage. 

Unit Record Applications: Because of the program- 
ming overhead in los due to virtual storage support, 
certain unit record applications may take longer in 
vsi than in mft. To avoid this situation the following 
applications can be run in a virtual=real (v=r) envi- 
ronment. 

OCR Applications — 1287-1288 programs which do not 
take advantage of jes run slower in a paged environ- 
ment than they would under os/mft. Testing has in- 
dicated that OCR applications from os/mft have no 
appreciable degradation when run v=r on vsi. 

Card Reader Applications — A job accessing a card 
reader and using the cntrl macro may run slower. 
This is due to the fact that these applications add 
processing time to the system overhead. This can be 
avoided by using the v=r facility. 

Unless you have these specific types of programs in 
your library, and have verified that the preceding sit- 
uations are present, running unit record jobs in v=r 
mode is not recommended and will have an adverse 
effect on system performance. 

Virtual=Real Storage Availability 

The system default for the size of the v=r area is 512K 
or the real storage size of the machine, whichever is 
less. For systems larger than 512K, the user can specify 
a v=R area greater than 512K and less than or equal to 
the real storage size of the machine. He must specify 
this value at system initialization time in response to 
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No firm rules or proven formulas exist for determining 
the amount of real storage that will be available for 
virtual=real execution in the system at a given time. 
This is due to the number of system operations that 
affect the availabihty of real storage space. However, 
the following considerations should help the user to 
understand the system use of real storage and to plan 
his work load and workflow accordingly. 




Figure 14. Contents of Virtual Storage with Virtual = Real Specified 



Concepts 27 



The size of the sysgened nucleus afiEects the amount 
of real storage available for v=r execution. The 
basic nucleus for a 128K real storage system operat- 
ing one partition requires 64K. This includes 6K for 
Recovery Management Support (rms) and 4K for 
System Queue Area (sqa). As more features, op- 
tions, or support are sysgened in, the nucleus size 
increases and less real storage is available for v=r 
operations. 

When a request for v=r area is received, the sys- 
tem scans the v=r area for the requested amount 
of contiguous real storage. If an area is located that 
contains unused pages, the request for v=r space 
can be honored immediately. If a conditionally suit- 
able area (containing no long-term fixed pages) is 
located, it is assumed to be conditionally available 
to honor the v=r request. Pages within this area are 
tagged for interception and subsequent use for v=r 
execution. When all pages in the area are no longer 
required for currently executing programs and have 
been paged out or relocated in real storage, the area 
becomes available and the v=r request can then be 
honored. 

Real storage for sqa, when specified at sysgen or 
NIP time, is appended to the nucleus. This real stor- 
age, like the nucleus and rms area, is not available 
for v=R execution. If too little sqa has been speci- 
fied, the system will dynamically extend the sqa, in 
increments of 2K bytes, as required. The extension 
will probably last until the next ipl. This extension 
further reduces the v=r area and may additionally 
cause real storage fragmentation, since the 2K ex- 
tension will be located in what the system deems 
the optimum loci.tion. This location may not be the 
most optimum from the standpoint of v=r execu- 
tion. As a worst case example, the extended sqa 
might be located in the middle of the v=r area, 
which would reduce the contiguous available stor- 
age in the area by half. 

Protected Queue Area (pqa) space also affects the 
amount of available v=r space. At initial partition 
definition time, a minimum of 2K of real storage is 
reserved for pqa for each partition defined. If addi- 
tional pqa is required during processing, the system 
also extends the pqa in increments of 2K bytes. 
These increments are also placed in the optimum 
location from the system standpoint and this may 
cause the same sort of fragmentation as noted for 
sqa extension. In all events, the pqa is not avail- 
able for v=R execution. As with sqa, the pqa exten- 
sions will probably last until the next ipl. 



• PCI FETCH, if used, can cause a fixed pqa or sqa 
overflow. Each time a module must be brought into 
virtual storage, a 1600-byte work area is required 
and must be fixed. If the request is from a problem 
program, the work area is taken out of fixed pqa. 
If the request is from the system, the work area is 
taken from fixed sqa. Extensions of pqa and sqa 
are handled as previously described. 

• JES (Job Entry Subsystem) requires one page of 
real storage to be long-term fixed. This page will be 
fixed right after nip time and will remain for the 
duration of the ipl. 

• Some components of the system cannot tolerate 
page faults during their operation. A page fault 
occurs when a "page not in real storage" is referred 
to by an active page. To eliminate the possibility 
of page faults occurring, these components may 
"long-term fix" required pages in real storage. These 
pages cannot be moved within real storage or paged 
out to auxiliary storage. These pages are fixed by 
the system in optimum locations (for system use) 
and may cause the same storage fragmentation and 
reduction of v=r area as previously noted. These 
pages remain fixed until they are freed by the com- 
ponent, at which time additional contiguous v=r 
area may become available. 

• The system reserves an area of 36K that is used for 
Excp i/o (short-term fixes) and paging. Two pages 
of this area are reserved as a "safety valve" in ca^e 
PQA or SQA needs to be extended due to an overflow 
condition. This area is reserved to reduce the possi- 
bility of the system being unable to continue pro- 
cessing due to lack of real storage to accept pages 
needed for system functions. The area may, or may 
not be used by the system, but it is reserved and 
further reduces the area available for v=r requests. 
The reservation remains the same, regardless of the 
real storage size of the system involved. On a small 
real storage size system, this can be a significant 
factor in v=r area availability. 

• vsi is a paging system. Real storage is managed by 
the control program in a manner that will prove 
most efficient for currently executing programs. 
This may prove to be the least efficient for v=r 
operations. The system will make all effort possible 
to honor requests for v=r area, but current opera- 
tions still take precedence. 

With the number of variables that can occur in real 
storage usage during system processing, it is impossi- 
ble to predict v=r storage a\'ailability at any given 
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time. Each installation will have to depend upon expe- 
rience to determine the most feasible allocations for 
SQA and PQA based on job mix and job flow for the in- 
stallation. Experience should also determine when it is 
most feasible to run jobs with v=r requirements. In 
theory, they should be run as soon as possible after 
IPL to assure the maximum provision of available v=r 
area. 



System Output Writers 

System output writers, resident in partitions as they 
are in os mft, do not exist in vsi. Instead, system 
output, with the exception of direct system output, is 
written bv tes outout writer I's). resident in the page- 
able supervisor area of storage. For additional infor- 
mation concerning the jes writer, see the explanation 
under the heading Output Writers in this section. 

Direct System Output Writer Partitions: Direct sys- 
tem output writers operate in partitions. To control the 
writing of a job's output, the direct system output 
writer must be operating in the same partition as the 
job; also, the job's class must be an eligible job class. 
An eligible job class is one that has been assigned to 
the direct system output writer when the writer was 
started. Direct system output writers can handle up to 
15 different job classes. 



Checkpoint/Restart 

The checkpoint/ restart facility permits a restart either 
at the beginning of a job step (step restart) or at a 
checkpoint within a job step (checkpoint restart). 
A checkpoint is requested by issuing a chkpt macro 
instruction; a step restart is requested by including 
special parameters in the job control statements for 
the job. 

In a checkpoint restart, the restart must be executed 
in the same virtual storage area as was used for the 
original execution. The required virtual storage must 
be contained within one partition. Furthermore, the 
partition must be a problem program partition. Restart 
may also be delayed if a define command entered by 
the operator changes the boundaries of the partition. 
In a step restart, there are no such restrictions. 

A CHKPT macro should not be issued by a subtask or 
by a job step task that has active subtasks. 



Partition Redefinition 

Partition redefinition allows the operator to change the 
number of partitions, their size, and their job classes 
at any time after initial program loading (ipl). Adja- 
cent partitions may be combined to accommodate jobs 



with large storage requirements; these partitions may 
be reestablished subsequently (within system genera- 
tion limits) when the need for a large partition has 
passed. Job classes assigned to a partition may be 
changed also, to accommodate changes in the work 
load for one or more job classes. 

In addition, if the time-slicing feature is included 
in the system, the number of time-slicing partitions 
can be decreased, or increased within system genera- 
tion limits, the range of the highest and lowest parti- 
tion number to be time-sliced can be changed, or the 
amount of time to be allotted to each task can be 
modified. All time-slicing attributes may also be can- 
celed. 

Partition redefinition is invoked in any of three 
ways, depending on whether it is invoked during or 
after system initialization. At system initialization, the 
partition configuration may be changed by replying 
'yes' to message ieesoid 'change paetitions?'. Alter- 
natively, partition redefinition may be invoked after 
system initialization by entering the operator com- 
mand, define, either with or without the keyword 
PARM=membername. Without the keyword, the op- 
erator redefines the partitions manually. With the 
keyword, the system redefines the partitions auto- 
matically by referencing a member in sysi.parmlib. 
For further information, see the VSI Features and 
Options section. 

Note: The DEFINE command cannot be entered through the 
input stream. 



Partition Combination 

Adjacent partitions may be combined as soon as their 
jobs have been terminated. If an unending job is being 
executed in a partition that is to be combined with an 
adjacent partition, the unending job must first be ter- 
minated with a cancel or stop command. All other 
partitions that are to be combined are made quiescent 
by the system as soon as their current tasks are com- 
pleted. Any number of adjacent partitions may be com- 
bined. For example, in Figure 11, P2 and P3 may be 
combined into one larger partition of 128K. However, 
P2 and P4, PI and P3, may not be combined. When P2 
and P3 are combined, the new configuration is as 
shown in Figure 15. P2 or P3 may be made the inac- 
tive partition. When P2 and P3 are combined, the job 
classes to be serviced by the new partition (P2) must 
be determined. If no change in job class (es) is speci- 
fied, the classes currently being serviced by P2 remain 
as the job class assignments of the new partition. (See 
Identity Change. ) The inactive partition ( P3 ) is made 
nondispatchable until it is recovered. 
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Figure 15. Partition Configuration after Combination 
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Figure 16. Partition Identification after Combination 



With the storage protection and fetch protection 
features, a unique protection key is available for each 
problem program partition. A list is kept of each avail- 
able key for subsequent reassignment to combined or 
recovered partitions. When partitions are combined 
or recovered, the first available protection key on the 
list is assigned to them. 

Note: Storage assignment increases through partition redefini- 
tion should be made in increments of 64K bytes. If they are not, 
the system rounds the value to the next 64K increment. 

Identity Change 

Partition redefinition also allows the job classes speci- 
fied at system generation or at system initialization to 
be changed. When partitions are combined or recov- 
ered, the job class (es) that will be assigned to the 
resulting partitions must be determined. In Figure 15, 
P2 and P3 were combined into the larger partition P2. 
However, the original partitions each had three job 
classes. Therefore, the decision must be made whether 
to choose new job classes or some combination of the 
six old classes. For example, P2 could be assigned job 
classes C, A, and M, or a new job class could be speci- 
fied, such as O. A new configuration is illustrated in 
Figure 16. If a new job class identifer(s) is not in- 
cluded during partition combination, the job class ( es ) 
originally assigned to the partition which remains ac- 
tive is unchanged. As a result, some jobs already en- 
queued on the input queue may not have a partition 
assigned to service them. 



Partition Recovery 

Partitions that were combined may be reestablished, 
or recovered. In Figure 15, P3 is now inactive, but is 
to be recovered. Once again the decision must be made 
as to which job classes will be assigned to both P2 and 
P3. P2 and P3 need not retain their original size, nor 
their previous job classes. With P3 recovered, Figure 
17 shows a possible new configuration. 

Note: When recovering partitions, a job class(es) must be 
specified for the partitions being recovered, since only the cur- 
rently active partition has a job class(es) assigned. 

Partition Definition Processing 

As shown in Figure 18, when the operator enters 
either define or the reply 'yes' to the 'change parti- 
tions?' message, the system requests that the defini- 
tions be entered. If 'list' was specified, the system 
lists the current partition configuration, including the 
time-slicing specifications, if this feature was chosen. 
(The operator must remember to cancel all affected 
unending jobs before redefining the system. If he does 
not, the new partition definitions do not take effect.) 
After definitions are entered, the system checks their 
validity and also inhibits scheduling subsequent jobs 
into the affected partitions. The system will stop any 
active direct system output writer in the affected parti- 
tion. When the current jobs have been terminated, the 
new definitions are implemented. The Conmderations 
section contains operating considerations associated 
with partition redefinition. 
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Figure 17. Partition Configuration after Recovery 
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Figure 18. Partition Definition Processing 



Input Readers 

vsi allows the user to speeify as many input readers 
as he desires, within the Hmits of the virtual storage 
allocation he has made for his jes area at sysgen time. 
The readers are part of jes, are resident in the page- 
able supervisor area of storage, and operate concur- 
rently with writers and with problem programs. The 
maximum number of readers required is specified at 
sysgen time in the rdr parameter of the jes macro in- 
struction or at IPL time by the jes reconfiguration facil- 
ity. One reader is assumed if the parameter is omitted. 

All input to vsi, except console-entered commands, 
passes through the jes reader(s). The jes reader is 
started for each input stream by entering a start com- 
mand, and it continues to service an input device 
until terminated by a stop command or until end-of- 
file is encountered on a device other than a card reader. 

When the jes reader is initialized, the Job Entry 
Peripheral Services (jefs) monitor, a part of jes, ini- 
tializes work area storage for input stream dependent 
information and attaches the reader as a subtask for 
each input stream started. The reader examines the 
records and separates them into commands, job con- 
trol, and data. 
The functions of the jes reader are to: 

1. Scan each job statement for valid jobname, class, 
type of run, and priority keywords. 

2. Obtain a time stamp containing the start time as 
each job is encountered in the input stream. 

3. Give an internal vsi identification consisting of a 
number concatenated with the job name. 

4. Send to the command processing section of the jes 
reader all commands not within a job. The com- 
mand is processed according to a specified disposi- 
tion that may include: 

• Execute the command. 

• Write the command on the console and execute. 

• Write the command on the console and ask the 
operator whether or not to execute. 

• Ignore the command. 

5. Put all the jcl for the job into a jcl spool data set. 
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6. Take a job-end time stamp when the job has been 
completely read. The real tunc in the jes reader is 
calculated for the job. The total number of state- 
ments read for the job is available at this time. If no 
error has been encountered, the job is enqueued by 
class and priority on the job queue. If an error has 
been encountered, the job is deleted and, if an un- 
recoverable i/o error occurs, the reader is closed. 



7. Bypass all input from the input stream, if requested, 
until a job with a specified name is encountered. 

8. Complete processing for the current input stream 
when an end-of-file is encountered on all devices ex- 
cept a card reader. The jeps monitor is called to 
indicate that the reader has been stopped. 
Figure 19 is a graphic representation of jes input 

reader processing. 




Figure 19. |ES Input Reader Processi^::! 
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Enqueuing Jobs by CLASS and PRTY 

A job definition, containing a disk entry record and 
accounting records, is created for each job read by the 
input readers and is placed in the queue specified by 
the CLASS parameter. Jobs are entered into the input 
work queues for each class according to the prty pa- 
rameter (pRTY values range from a low of to a high 
of 13 ) . One input work queue exists for each of the 15 
job classes. Jobs having the same class and priority are 
placed in the queue first-in/ first-out (fifo). When the 
input work queue for a job class contains one or more 
jobs, termination of a job in any partition assigned to 
service work for that job class is followed by selection 
of the next highest-priority job from the input queue. 
Selection and initiation of the new job does not require 
operator intervention. 

For example, if class=d, prty=12 is specified on the 
JOB statement, the job is placed on the input work 
queue for job class D, behind any previously enqueued 
PRTY=12 jobs, but ahead of all jobs of lower priority. 

Note: If no PRTY parameter is specified on the JOB card, 
the job is assigned the default priority specified in the reader 
procedure. 

The PRTY parameter applies only to initiation prior- 
ity, not to dispatching priority. Dispatching priority 
determines which job should be given control of the 
CPU. In vsi, dispatching priority is derived from the 
relative position of the partitions: PO has highest prior- 
ity, P51 lowest. 

The dispatching priority of a task is determined by 
the relative position of the task control block (tcb) 
on the dispatching queue. (The dispatching queue is 

If subtasking is not used, all tcbs are established in 
the nucleus at system generation. These are ordered to 
provide a dispatching priority starting with resident 
system task tcbs, through the job step task tcb of the 
highest priority partition (PO), to the successively 
lower priority partitions' tcbs ( P1-P51 ) . Control of the 
CPU is given to the program represented by the highest- 
priority ready tcb. 

If subtasking is used, tcbs established at system 
generation in the nucleus represent the resident system 
tasks and the job step task of each partition. However, 
each job step task can attach subtasks, each of which 
will have a tcb located in the partition's protected 
queue area. The dispatching priority is initially the 
same as the partition's priority. The dispatching pri- 
ority differs from the partition's priority when a job 
step task issues a chap (change priority) macro in- 
struction to change its dispatching priority. If dis- 
patching priorities are not changed, each partition's 
job step task is dispatched before its subtasks, which 
are then dispatched in the order in which they were 



attached. When all of a job step's subtasks have been 
dispatched, the job step task of the next lower partition 
can be dispatched. 

If the time-slicing feature was specified at system 
generation, the effective dispatching priority of a group 
of time-sliced partitions can be altered. Time-slicing 
allows the user to establish one group of consecutive 
partitions in which the task in each of the partitions is 
assigned a uniform interval of time to retain control of 
the CPU. When the allotted time has elapsed, the next 
lower-priority ready task gains control of the cpu for 
its allotted time. This process continues until either all 
tasks are waiting and completed, or until a task of 
higher-priority becomes ready. 

Job Initiation and Termination 

The job scheduler contains the initiation, interpreta- 
tion, allocation, and termination portions of the control 
program. As illustrated in Figure 20, the job initiation 
portion selects jobs from input work queues and deter- 
mines which type of output writer to use for each out- 
put class. As each problem program is executed, it 
retrieves its input (sysin) data from the direct access 
device where it was previously stored by the input 
reader. (Note that this retrieval takes place at direct 
access speeds, which is faster than reading input data 
directly from a card reader. ) During problem program 
execution, output data directed to an output class is 
recorded on a direct access device, or written directly 
to the output device, depending on the type of output 
writer selected. 

Jobs are scheduled for execution according to: 

1. Their job class identifier. 

2. Their priority within the job class queue. 

3. nil avaiiauie partition corresponuing to tne appro- 
priate job class. 

When a job is complete, the scheduler performs the 
required termination and informs a system output 
writer that the data produced by the problem program 
is ready to be written on the specified device. 

Job Initiation 

An initiator may be started in each problem program 
partition that is defined at sysgen time. When each 
initiator is started, job management allocates an area 
on DASD called swads ( scheduler work area data set ) . 
Each swADS holds the tables for the problem program 
currently handled by that particular initiator. Thus, it 
is a sequential data set that is reusable; that is, the 
tables for a new job overlay those from the previous 
job. The swADS is deallocated when the stop command 
for that initiator is processed. (For a description and 
discussion concerning sysi.sysjobqe, see section jqf in 
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Figure 20. The VSl System 



the Use portion of this manual.) The initiator selects 
a job from the input work queues established by the 
system input reader and schedules it for execution. 
Initiators obtain jobs for partitions based on the job 
classes assigned to the partitions, and the priority of 
the jobs within their job classes. The initiator inter- 
faces to allocation procedures for device allocation. 
The job is then scheduled for execution. An initiator 
is given control after a job has been terminated. 

When the job terminates, the initiator then sched- 
ules the next available job into its partition and passes 
control to the first step of that job. When system out- 
put writers are used, output data sets are placed on 
direct access storage devices while the job is being pro- 
cessed. The output data sets are enqueued by output 
class and subsequently retrieved by system output 
writers, 
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Job Termination 

The termination portion of the control program deter- 
mines first whether step termination or job termination 
is to be performed. Step termination includes dispos- 
ing of data sets, deallocating input/ output devices, 
processing condition codes, and executing an account- 
ing routine. If the job contains additional steps, control 
is returned to the initiator to schedule the next job 
step. Job termination is performed after the last step 
of a job has been terminated. An accounting routine 
is executed; data set disposition and input/ output de- 
allocation that could not be done at step termination 
are completed. 

If the job used direct system output writers, its out- 
put was written directly to an output device or devices : 
no intermediate device had to be used and no output 
work is enqueued. 



If the job used system output writers, its output is 
entered in the output work queue for processing by 
the system output writer. Output work queue members 
are enqueued within output class according to the 
PRTY parameter on the job card. Jobs having the same 
output class and priority are placed in the queue fifo. 
For example, if a single output class is specified for 
system messages and all output for a particular prob- 
lem program, the output work queue for that class 
includes, at job termination: 

1. All system messages produced at job initiation, such 
as allocation messages. 

2. All system messages produced during job termina- 
tion, 

3. All problem program output. 

This output is transferred to the specified output 
device in the order shown. Different types of output, 
such as system messages and problem program data, 
are never intermixed. 

Data sets for a job are enqueued on the output work 
queue according to output class and priority, so that 
they can be written by an output writer. These data 
sets may include data sets produced during a job step, 
as well as control program messages. Depending on 
its characteristics and the way it is to be processed by 
the control program, a data set may be assigned to any 
one of 36 output classes (A-Z, 0-9) defined at an in- 
stallation. A particular output class may reflect such 
characteristics as priority of the data, type of device 
to record it, or location or department to which it is 
to be sent. ( See Choosing Output Classes in the Con- 
siderations section. ) 



Direct System Output Writers 

Direct system output writers write problem program 
and system messages, produced by the initiator/ termi- 
nator, directly to system output devices. Valid output 
devices are: printer, punch, and magnetic tape. 

Direct system output writers are started in problem 
program partitions and are initialized before the prob- 
lem program gets control of the partition. When the 
problem program writes its output, the output will go 
directly to the output device assigned to the direct 
system output writer. System output writers can han- 
dle as many as 15 different job classes. If no job 
class (es) is specified in the start command, job classes 
to be processed are obtained from: 

First, the partition information block; then, the direct system 
output procedure. 

If job classes are specified in the start command, they 
override those specified in the other two sources. For 
example: if the operator enters the command. 



START DSO.P3,283„(JOB CLASS =ABC,OUTCLASS = B) 

any job running in partition 3 with a jobclass of A, B, 
or C and an output class of B will have its output writ- 
ten directly to tape device 283. 

The job class and output class of a direct system out- 
put writer can be changed by use of the modify com- 
mand. For example: if the operator enters the com- 
mand, 

MODIFY 283, JOBCLASS = DE,OUTCLASS = A 

any direct system output writer writing to output 
device 283 will process jobs with a jobclass of D or 
E, and an output class of A. 
Direct system output writers can be stopped by a 



partition id, which will cause all dso in the partition 
to be stopped, or it may specify a device, which will 
cause only dso to the particular device to be stopped. 
A user-supplied dso procedure may be used, but it 
must execute the iBM-supplied direct system output 
writer. 



Output Writers 

Output writers write system output data sets created 
by problem programs, and system messages produced 
by the initiator/ terminator tasks. All system output 
data sets are written on direct access storage devices. 
These are used as the input data sets for the output 
writers. Valid output devices for an output writer are 
printer, punch, and magnetic tape. 

When a job is terminated, system messages and out- 
ran f nnffl nrp» <=>nnnp>np>r1 in tViP> a-nr»rnr>riQfp> cvct/^m mit- 

put queue. One system output queue exists for each 
output class. Queues are serviced in the order specified 
in the start command for the writer. As many as eight 
output classes may be specified. These classes override 
those in the writer cataloged procedure. The writer 
dequeues the first entry from the primary queue. If 
there are no entries in the primary queue, the writer 
dequeues the first entry in the secondary queue. This 
continues through the eighth queue, or until the writer 
finds work. 

vsi allows the user to specify as many system out- 
put writers as he desires, within the limits of the vir- 
tual storage allocation he has made for his jes area 
at sysgen time. The writers are part of jes, are resi- 
dent in the pageable supervisor area of storage, and 
operate concurrently with readers and with problem 
programs. The maximum number of writers required 
is specified at sysgen in the wtr parameter of the jes 
macro instruction or at ipl time by the jes reconfigu- 
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ration facility. One writer is assumed if the parameter 
is omitted. 

All vsi output data, with the exception of direct 
system output data, must pass through the jes writer. 
The data includes output data sets and data sets con- 
taining system messages and job control language. The 
writer is invoked for each output stream by entering a 
START command. It continues to service an output de- 
vice until terminated by a stop command. 

When the jes writer is initialized, the jeps monitor 
initializes work area storage for output stream depen- 
dent information and attaches the writer as a subtask 
for each output stream started. 

The JES writer uses job entry central services to 
obtain output data and system messages in the order 
they appear in the specific output class queue. The 
writer processes one copy of the job's jcl, system mes- 
sages, and output data set, unless otherwise specified. 
Multiple copies can be provided by so specifying in 
the job's JCL, or by the writer command. 

When all output for a job is processed, an account- 
ing linkage routine is called for final job accounting 
and the job is completely removed from the system. 
At this time, the space held by the job on the spool 
and queue devices is freed. 

A user-written output writer procedure may also 
be used. This procedure may execute a user-written 
writer program or the iBM-supplied writer. If a user- 
written writer procedure is used, it must be placed in 
SYsi.PROCLiB and named in the start command. 

System Restart 

Because it is sometimes necessary to shut down the 
system ( end-of-shift, end-of-day, normal maintenance, 
or system malfunction), system restart allows the sys- 
tem to resume operation without having to reenter jobs 
that have been enqueued. Information concerning jobs 
on the input, hold, and output queues, and jobs in in- 
terpretation, initiation, execution, or termination, is 
preserved for use when the system is reloaded (see 
Figure 21 ) . When the system is restarted, the operator 
receives messages describing the status of each job 
in the system. If the job was not enqueued, the job- 
name is written out at the console. If the job was under 
control of a scheduler, the jobname and stepname are 
given. In addition, the operator is informed of whether 
allocation was being performed for the job, or whether 
the job was being executed or terminated. 

Invoking System Restart 

After the system is reloaded, and after nucleus initiali- 
zation, system restart may be invoked by omitting the 
"F" suffix from the Q=(unitname,[F]) parameter of 
the set command, or by omitting the Q=parameter 




Figure 21. System Restart Processing 
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entirely. This is valid only for the initial set command, 
and cannot be done at any other time. This omission 
indicates to the system that the job queue data set 
(sysi.sysjobqe) already exists in proper format, and 
requires only initialization. 

Jobs that Were Being Read In 

When the system must be restarted, jobs that were 
being read in are deleted from the job queue and must 
be resubmitted. 



Jobs on Input, Hold, and Output Queues 

All jobs that were enqueued on their appropriate job 
class hold or output class "^ueues vcTn/iin there for 
subsequent processing when the system is restarted. 
No operator action is required. 



Jobs that Were Dequeued 

Jobs that were dequeued from an input or hold queue 
may or may not have been completely interpreted. If 
interpretation was not complete, system restart re- 
enqueues the job where it will be subsequently de- 
queued by an initiator and reinterpreted. If interpre- 
tation was complete, the job will be scheduled for 
restart if possible. Otherwise, the job will be canceled, 
and output data sets created for the job will be en- 
queued. 

With the restart facility, any job that was in step 
termination at restart time is executed starting at the 
next ste^^ of the ^'ob after s^'^stem restart is com''^lete. 
Any job that requested restart is restarted at the cur- 
rent step, after system restart is complete, if the fol- 
lowing conditions are satisfied: 

• The step completed the allocation phase (that is, 
the phase between allocation and step termination ) . 

• System completion code 2F3, designating system 
restart, was specified as eligible for restart. 

• The operation replied yes to the verification request 
( message IEF225D ) to restart the job. 



System Output Processing 

Output jobs that were being processed by a system 
output writer are requeued to reprocess any data sets 
that had not been written completely at the time the 
system was shut down. No operator action is required. 
All system messages and data sets that had not been 
processed are written by the first eligible output writer 
started. System log data sets are queued to output class 
A by system restart routines. 



Standard and Optional Features 

The standard features included in vsi are: 

1. Same as os/mft. Release 20.1. 

2. Linkage Editor/ Loader. 

3. System Assembler. 

4. Storage Protection. 

5. Jobstep Interval Timer. 

6. Identify. 

7. Job Entry Subsystem. 

8. Recovery Management: 

a. MCH (Machine Check Handler). 

b. ccH (Channel Check Handler). 

9. Page Supervisor. 

10. Access Methods: 

a. BSAM. 

b. QSAM, 
C. BDAM. 
d. BPAM. 

11. Utilities: 

a. System UtiHties 

lEHATLAS 

lEHDASDR 

lEHINITT 

lEHIOSUP 

lEHLIST 

lEHMOVE 

lEHPROGM 

IFHSTATR 



lEBCOMPR 

lEBCOPY 

lEBDG 

lEBEDIT 

lEBGENER 

lEBISAM 

lEBUPDTE 

lEBPTPCH 

IEBTC3RIN 



c. Independent Utilities 



IBCDASDI 

IBCDMPRS 

ICAPRTBL 

12. Service Aids: 

HMAPTFLE 
HMASPZAP 
HMBLIST 
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hmdprdmp 

hmdsadmp 

ifcdipOO 

ifcerepO 

imcjobqd 

Generalized Trace Facility ( gtf ) 

13. Multitasking. 

14. On-Line Test Executive Program ( oltep ) . 

15. Remote Entry Services ( res ) . 

16. Automated System Initialization. 

17. Partition Deactivation /Reactivation, 

18. Missing Interruption Checker. 

19. Automatic Partition Redefinition. 

20. User Modify Logical Cylinder Facility. 

21. Greenwich Mean Time ( GMT ). 

The optional features available for vsi are: 

1. Selected resident SVC routines. 

2. Selected resident modules from linklib. 

3. PCI FETCH. 

4. Operator communication during initialization. 

5. System Log. 

6. Dynamic Device Reconfiguration ( ddr ) . 

7. Checkpoint/ Restart. 



8. Multiple Console Support (mcs). 

9. System Management Facility ( smf ) . 

10. Shared Direct Access Storage Device ( dasd ) . 

11. Device Independent Display Operators Console 
Support (didocs). 

12. Time Slicing. 

13. Access Methods: 

BTAM 
TCAM 

gsp/gam 

BISAM 
QISAM 
VSAM 
RTAM 

14. Alternate Path Retry. 

15. Automatic Volume Recognition (avr). 

16. Integrated Emulators. 

17. Conversational Remote Job Entry (crje). 

18. i/o Load Balancing. 

19. DEB Validity Checking. 

20. Dynamic Dispatching. 

21. Fetch Protection. 

22. Dynamic Support System ( dss ) ( for planning pur- 
poses only ) . 

23. Direct Access Volume Serial Number Verification. 
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Considerations 



In preparing for the use of vsi, data processing plan- 
ners and system programmers should evaluate not 
only the characteristics and requirements of the jobs 
to be processed by the system, but the characteristics 
and facilities of the system that influence how a job is 
processed once it has been presented to the system. 
Some of these characteristics are general and apply 
equally to all types of jobs. Others are related directly 
to job type. A third category of characteristics, al- 
though related to job types, is exhibited primarily in 
system operation, and must be considered by machine 
room supervisors and machine operators. 

In this section, the topic General Considerations 
describes items of interest primarily to planning per- 
sonnel, that should be considered before generation 
of a vsi system. The next four topics — Batch Pro- 
cessing, Telecommunications, Graphics, and Concur- 
rent Peripheral Operation — describe considerations 
important to the systems programmer and the applica- 
tion programmer. These four topics are organized 
similarly, in "checkHst" fashion, so that the reader 
interested in a given job type need read only General 
Considerations and the topic corresponding to the job 
type in which he is interested, to learn all considera- 
tions pertinent to that job type. Because partition 
configurations depend on the amount of real and vir- 
tual storage available as well as on the types of jobs 
to be run, the topic Typical System Configurations 
describes partition arrangements for systems with 128K 
bytes, 192K bytes, and 384K bytes of real storage. 
These configurations are general, but should be help- 
ful for planning. The seventh topic, Operating Con- 
siderations briefly describes characteristics of vsi that 
may affect operating procedures. 



General Considerations 

Several considerations apply to all phases of the sys- 
tem; these must be considered regardless of the type 
of job that is being run. They include: 

• Estimating storage requirements. 

• Using resident reenterable routines. 

• Placing system data sets on direct access devices. 

• Sharing direct access devices with other systems. 

• Choosing the number and size of partitions. 

• Specifying appropriate job classes. 

• Assigning job names. 

• Formatting problem program messages. 



• Choosing output writers. 

• Avoiding system interlocks. 

Estimating Storage Requirements 

Refer to the publication OS J VSI Storage Estimates, 
GC24-5094, for information on estimating the storage 
requirements for your system. 

Single Console vs. Multiple Consoles 

Through multiple console support (mcs), an installa- 
tion may use one primary (or master) console and 
multiple secondary consoles where each console is 
dedicated to one or more system functions (for ex- 
ample, tape library, disk library, or teleprocessing 
control). MCS services all consoles concurrently, cre- 
ating an environment for operator/ system interaction 
that gives each console the appearance of being the 
only console on the operating system. Each console 
operator receives only those messages from the system 
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to his assigned functions. 

MCS. provides the mechanism to: 

• Route messages to selected functional areas. 

• Allow a user-written exit routine to modify the 
message's routing and descriptor codes prior to the 
issuance of the message. 

• Switch to an alternate console if a primary console 
should fail. 

• Allow automatic message deletion on devices such 
as display tubes ( graphics ) . 

• Support a hard copy log for the recording of routed 
messages, operator commands, and system re- 
sponses. 

Selective message routing, provided under mcs, is 
the ability to route both problem program and system- 
initiated messages to functional areas and the syslog 
device. Messages appear only on consoles that have 
been specifically designated to receive the messages. 
In this manner, a console whose function is to receive 
tape messages, for example, is prevented from receiv- 
ing messages not pertinent to that function. 

A system generation option is provided to permit 
insertion of a resident, user-written exit routine in the 
communications task. The exit routine receives control 
prior to routing any wto and wtor messages whose 
routing codes will be used by the operating system. 
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The exit routine may examine but not modify the mes- 
sage text; however, the exit routine may modify the 
message's routing and descriptor codes. Messages will 
only be sent to those locations specified in the modified 
routing codes. 

Mcs permits console switching, which can be initi- 
ated automatically, by operator command, or by the 
operator manually pressing the interrupt key on the 
system control panel: 

• Automatic console switching to an alternate con- 
sole occurs when permanent hardware errors are 
detected by the operating system. 

• Command-initiated console switching occurs when 
the system accepts a valid vary operator command. 
Command-initiated console switching is used to re- 
structure the system console configuration and the 
hard copy log. Console switching to an alternate 
console can be performed by placing the original 
console either online or offline. 

• Manual switching is Hmited to the master console 
( primary console device ) and is initiated by press- 
ing the interrupt key on the system control panel. 
Manual switching to a new master console is used 
when the master console is inoperative and the 
hardware failure cannot be detected by the system. 

Messages can be automatically deleted from the 
screen on the operator console with crt display by 
using the dom macro instruction. When a system or 
problem program no longer requires that a message 
be displayed — for example, if a wto macro instruc- 
tion was issued and the message is no longer needed — 
a DOM macro instruction should be issued to delete the 
message from the screen. 

MCS allows buffered or immediate hard copy. Thus, 
no information is lost when messages and operator 
commands are deleted from graphic displays. In addi- 
tion, the hard copy device can be used as a collection 
point for all messages and commands. Routing codes 
and the time, if the timer option is present, are pre- 
fixed to all messages and commands that are sent to 
the hard copy log. The system log — the only buffered 
hard copy device supported — ^must be specified at sys- 
tem generation, and can be modified at system initiali- 
zation or during system operation. If hard copy is 
desired on a console, the hard copy device can be 
specified at system generation, at system initialization, 
or during system operation. Although the system log 
is supported with or without the mcs option, the hard 
copy log is only supported with the mcs option. 

ISlote: If the multiple console support (mcs) option is selected 
when coding the schedulr macro instruction, a seconsle macro 
instruction must be included for each console except the master 
console; that is, for the alternate to the master console and for 
each additional secondary console. 



PARTITNS Macro Instruction 

The PARTITNS macro instruction must be used. It estab- 
lishes the maximum number of partitions for an instal- 
lation. The maximum number of partitions that an 
installation intends to use should be estabUshed at 
system generation, because this number can be re- 
duced during system initialization or during operation. 
Unnecessary system generations may be avoided be- 
cause the number of partitions in use may never 
exceed the number established at system generation. 
Therefore, if the maximum number of partitions that 
might be used at some later date is generated, the 
system does not have to be regenerated to increase 
the number of partitions in the system. The attributes 
of each partition are established as follows: 

Pn(C-class,S-size) 

where the characters P, C-, and S- must appear as 
shown. 

n specifies the partition number (0 to 51). 

class specifies the function of the partition as follows: 

S = system task partition 

XXX = problem program partition specified as alphabetic 
characters from A through O that indicate the job 
classes that can use the partition, 
size specifies the size of the partition from to the maximum 
in 64K increments without the K. 

Notes: 

• Partitions may be specified in any order as long as every 
partition in the sequence is included. 

• Partition sizes will be rounded up to 64K boundaries. 

• No more than 37 system task partitions may be specified. 

• At least 1, but no more than 15, problem program (user) 
partitions may be specified. 



Page Boundary Loading 

Aligning a control section or a named common area on 
a page boundary can be used to effect a lower paging 
rate, thus making more efficient use of real storage. To 
accomplish this alignment, the csect or common area 
is named on either the page statement or the order 
statement with the p operand. Either statement causes 
the linkage editor to locate the csect ( or common area ) 
on a page boundary within the load module. (When a 
note list is present, it precedes and is contiguous to the 
load module.) See OS/VS Linkage Editor and Loader, 
GC26-3813, for using page boundary alignment. 



Using Resident Reenterable Routines 

The resident reenterable load module feature allows 
problem programs to share reenterable code. It pro- 
vides improved performance by placing frequently 
used modules in the resident reenterable routine area. 
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Resident reenterable routines may be made non-page- 
able or pageable at the user's option. 

The feature uses the ram parameter to make pos- 
sible the pre-loading of both access method modules 
from the svc hbrary and any user-written reenterable 
modules from the link library. The feature uses four 
module Hsts created at system generation time. At 
system initialization, the user can either cancel the 
feature entirely or provide up to four different lists of 
access method and other reenterable modules of his 
own choosing to be loaded into the resident reenter- 
able routine area. 

In an operating environment where any problem 
program issues an attach, link, load, or xctl macro 
instruction to request use of a reenterable module that 
is not resident in its partition, the supervisor will search 
the resident reenterable routine area for the module. 
No additional copies need be brought into virtual 
storage. Therefore, frequently used reenterable load 
modules should be loaded into the area. Any user- 
written reenterable load module and the loader mod- 
ules from the link library can be loaded into the area 
by including it in one of the lists of modules specified; 
type 3 and 4 svc routines, however, must be loaded 
only into the rsvc area. 

Placing System Data Sets on Direct Access Devices 

Several factors must be considered when putting sys- 
tem data sets ( svclib, maclib, syspool, linklib, proc- 
LiB, parmlib, swads, PAGE, and sysjobqe) on direct 
access storage devices. If all nine data sets are on the 
same device, throughput is decreased because of ex- 
cessive arm interference. To increase throughput, data 
sets should be balanced on devices; devices should be 
balanced on channels. The ideal condition would be to 
have each data set on a different direct access device, 
and each device on a separate channel. In installations 
with smaller systems, it would be best to have sys- 
jobqe, SYSPOOL, and linklib on the same direct access 
device on channel 1, and svclib, proclib, parmlib, 
SWADS, PAGE, and maclib on another device on chan- 
nel 2. 

Whenever more than one Hbrary is to be placed on 
a 2314, 2319, 3330, or 3333 disk storage device, arm 
movement can be substantially reduced by placing the 
volume table of contents (vtoc) approximately mid- 
way between the first and last cylinders being used. 
The data sets, starting with the most frequently refer- 
enced, can then be alternately placed on both sides of 
the vtoc with the least referenced data sets farthest 
from the vtoc. 

Blocking the Procedure Library 

Blocking the procedure library conserves dasd storage 



space. The procedure library may be blocked during 
system generation or afterwards by using utilities. 

Blocking the procedure library during system gener- 
ation is done by pre-allocating the procedure library 
with recfm=fb and BLKSiZE=(a multiple of 80). Dur- 
ing stage II of system generation, the iehmove utility 
program blocks the procedure Hbrary on the new 
system. 

A preliminary study used a typical procedure library 
containing 54 procedures to determine the most ef- 
ficient blocking factor to conserve dasd storage space. 
Blocking factors from 1 to 40 (blksize=80 to 3200) 
were used. It was found that blocking factors in the 
range 8 to 12 were most eflBcient. For example, on a 
specific DASD, an unblocked procedure library required 
30 tracks but a blocked procedure library ( with block- 
ing factors in the range 8 to 12) required only 21 
tracks, a reduction of 30% in dasd storage space. 

Sharing Direct Access Storage Devices (DASD) 
with Other Systems 

If the shared dasd feature is selected at system genera- 
tion, considerations should be given to volume assign- 
ment and classification (read only or read/ write) of 
common data sets. Volume handHng and device reser- 
vation procedures must be carefully defined, because 
the shared dasd feature cannot prevent or resolve inter- 
locks between systems. 

Choosing Number and Size of Partitions 

The number of partitions needed at an installation de- 
pends primarily on the number of different job cate- 
gories (that is, batch, graphics, telecommunications, 
and cpo) expected to run concurrently. At least one 
partition must be specified for each category. The 
number of partitions for each category, based on the 
number of jobs expected to be run in each, should 
then be established. In practice, the maximum number 
of partitions for which there is available virtual storage 
should be established. If fewer partitions are needed 
during operation, the number of partitions can be 
reduced by the operator either at system initialization 
or during operation. If necessary, partitions may be 
reestablished up to the Hmit specified at system gen- 
eration. 

Note: If the maximum number of partitions is established at 
system generation, the size of the system queue area (sqa) at 
system generation also should reflect this maximum number. 
Then, if the number is reduced at system initialization, the sqa 
can also be reduced, by replying to message lEAlOlA 'specify 

SYSTEM parameters'. 

Within the limits of the system, the maximum num- 
ber of partitions that can be specified depends on the 
amount of real and virtual storage available. If a job 
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is known to exceed the size of its intended partition, 
an adjacent partition can be eliminated and its storage 
reassigned to the other partition. Reassignment of con- 
tiguous partitions can be accompHshed without inter- 
fering with unaffected partitions. 

Choosing Appropriate Job Classes 

A system installation can be set up for maximum ef- 
ficiency and throughput by properly using the partition 
job class concept. Particularly, the processing charac- 
teristics of jobs likely to execute concurrently must be 
examined. Failure to consider job mix can lead to de- 
grading system performance. Multiprogrammed jobs 
can, under certain circumstances, run slower than they 
would if processed sequentially. The required balance 
can be achieved simply with proper use of the class 
parameter by: 

• Estabhshing the job characteristics to be controlled, 
based on the typical processing workload. 

• Establishing a suitable partition structure com- 
patible with the job characteristics to be monitored. 

• Establishing the convention that jobs having cer- 
tain characteristics are to be directed, through the 
CLASS parameter, to the appropriate partitions. 

Typical job characteristics are: 

• High compute, low input/ output time. 

• Balanced compute and input/ output time. 

• Low compute time, high input/ output time. 

• Use of specific types of input/ output equipment, 
such as 2250 terminals, magnetic tape only, or tele- 
communications terminals. 

• Large real storage requirements. 

• Small real storage requirements. 

• Large virtual storage requirements. 

• Small virtual storage requirements. 

• Setup or non-setup jobs. 

• Use of preallocated data sets. 

• Time-slicing considerations. 

With this type of categorization, job mix can be 
balanced for improved throughput. For example, one 
partition can be established for high-input/ output jobs 
and another for high compute-time jobs. Process- 
limited jobs ( such as compilers ) can then be assigned 
to the high compute-time partition, and jobs with high 
input/ output requirements (such as sort programs, and 
reading and writing of data sets) to the input/ output 
partition. Normal job scheduling should then produce 
a satisfactory job mix. Because jobs are queued by the 
CLASS parameter, and because each partition is sched- 
uled for its next job immediately after the preceding 
one is complete, the system as a whole tends to exe- 
cute complementary jobs concurrently. 



The CLASS parameter may also be used to direct jobs 
that are to be time-sliced to partitions that were de- 
fined as time-slicing partitions. However, when using 
the time-slicing feature, caution should be taken when 
assigning a job class to a particular job. If a job is to be 
time-sliced, it must be assigned a job class that will 
be serviced by a time-slicing partition. Likewise, if the 
job is not to be time-sliced, it should not be assigned 
a job class that a time-slicing partition has been as- 
signed to service. 

A partition should be established to service each job 
class specified on a job card. If a job is assigned to an 
uuser viced job class, it remains on the input queue for 
that class indefinitely, or until the operator discovers 
(by use of the display n command) that the job has 
not been executed. 



Default Job Class 

If no CLASS parameter is specified on the job card, the 
system assigns job class A to the job. Therefore, a 
partition should not be assigned to service job class A 
unless all jobs run at the installation will fit into that 
partition. It is advisable to make job class A either a 
secondary or tertiary job class in one or more parti- 
tions, to ensure that any jobs that are assigned the 
default job class will be executed. 

The default job class is given to a job only when no 
CLASS parameter is specified, not when an incorrect job 
class is given. For example, if P2 is specified as job 
classes M and L (Figure 11), P3 as C, J, and A, and 
P4 as N, C, and D, the following job card illustrates 
an invalid job class specification: 

//MFT JOB ,'MYJOB',MSGLEVEL=0,CLASS=G 

Because job class G is an invalid job class for this 
particular configuration, the job will not be assigned 
job class A. It is placed on the class=g queue, and is 
never initiated. It remains there indefinitely until the 
operator discovers that the job has not been executed. 
Therefore, extreme caution should be used when 
choosing a job class for the job to ensure that a parti- 
tion has been specified for that job class. To prevent 
delays in processing jobs with "invalid" job class desig- 
nators, the operator should enter display n periodically 
to obtain a listing of the jobs on the hold and input 
work queues. Jobs with class= specified outside the 
range A-O ( for example, class=p ) will be abnormally 
terminated. 



Priority Scheduling within Job Classes 

Jobs within job classes can be initiated according to a 
priority specified in the prty parameter on the job 
card. For example, several jobs may be designated job 
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class B. Within this group of jobs, some are to be 
initiated before others. Therefore, higher priorities can 
be assigned to these jobs with the prty parameter. 
This affects only the way the job is initiated, not the 
way it is dispatched. If no prty parameter is specified, 
jobs are assigned the default priority established in 
the reader procedure and are initiated fifo for each 
job class. Therefore, each group of jobs for a partic- 
ular job class should be analyzed to determine if some 
are to be initiated before others, and to assign these 
preferred jobs higher priorities. 

Assigning Job Names 

Any valid job name is acceptable to the vsi system. 
Therefore it is possible that jobs with identical job 
names could be in the system at the same time. TTiese 
duplicate-name jobs could be on the same input 
queues, difiEerent input queues, or executing in dif- 
ferent partitions. The existence of these duplicate-name 
jobs could cause confusion when using the display, 
CANCEL, HOLD, RELEASE, and RESET commauds. For ex- 
ample, if a CANCEL command is entered for a job in 
the hold queue or an input queue, the system will 
cancel the first job encountered if duplicate job names 
are in the queue. 

To prevent this confusion, a procedure should be 
established which will ensure that all 'obs have uniQue 
names. This could be done, for example, by varying a 
portion of the jobname, that is, jobpayi, jobpay2, etc., 
to reflect sequence of input. Other methods of unique 
identification for jobs could be derived from appHca- 
tion, programmer's name, time-of-day, date, or any 
combination of these which would satisfy the needs of 
an installation. 

In addition, job names of PO, PI, . . . P51 should not 
be assigned because these are the partition identifiers. 
For example, if a job is assigned a name of P4, and a 
CANCEL command is entered for this job, both the job 
named P4 and the job that is running in partition 4 
will be canceled. 

Formatting Problem Program Messages 

In vsi it is necessary to relate wto and wtor mes- 
sages to the problem program which issued them. In 
order to do this, a partition identifier is added to each 
message issued by a problem program partition. The 
maximum length of wto messages is 122 characters. 
The maximum length of wtor messages is 119 char- 
acters. 
The vsi form of a vno message is: 

PHASE A ENTERED Pn 
Similarly, wtor messages in vsi include the partition 
identifier as follows: 

id REPLY 8 CHARACTER NAME Pn 



Single Reader or Multiple Readers 

In determining whether to have more than one reader, 
the number of problem program partitions necessary 
for the installation should be considered. It might be 
advisable to specify more than one reader. For exam- 
ple, the user could specify one reader for cards, one 
reader for magnetic tape, and a third for disk. 

The primary consideration is to analyze the jobs and 
to determine which input device will have the majority 
of the input in terms of cpu time. If this device is the 
card reader, then one reader should probably be speci- 
fied to read the input stream from the card reader 
continuously. If, on the other hand, there is a long 
input stream on magnetic tape and/ or direct access 
storage, a reader should be specified for each of these 
devices. If there is only one long input stream, it would 
be advisable to specify one reader for that particular 
device. 

Choosing System Output Writers 

If possible, records to be written by a system output 
writer should be blocked. This improves throughput, 
because less input/ output time is required, and disk 
arm interference is reduced. However, additional vir- 
tual storage must be provided within the problem 
program partition, where the records are initially 
blocked, and within the jes area, to which the logical 
records are read. (The additional space required, in 
each case, is equal to the logical record length times 
the blocking factor plus the input buffer space. ) 

Choosing Direct System Output Writers 

Since the user has a choice between direct system out- 
put writers and system output writers, the following 
factors should be ( 
type of writer to use: 

• Each direct system output writer can process only 
one output class per partition and needs one i/o 
device assigned to it. In a system with several active 
partitions, there will probably not be enough i/o 
devices to run direct system output writers in all 
partitions for all output classes. In this case it is 
possible to have jobs running with more than one 
output class. A direct system output writer could 
handle one output class and system output writers 
could handle the others. 

• Direct system output writers cannot handle output 
from system tasks, jobs canceled while on the input 
queue, and jobs failed by the reader/ interpreter. It 
is necessary to start a system output writer to han- 
dle these types of output. 

• System output writers and direct system output 
writers could be used together. If the output queue 
is filled, direct system output writers could be 
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started in the active partitions. This would allow 
the system output writers to clear the output queue, 
without stopping work in the problem program 
partitions. 

Use of Multiple Writers 

The use of multiple output writers has several advan- 
tages. In general, a unique output writer can be used 
for each requirement in the system. For example, the 
following output classes might be assigned: 

• An output class for all system messages. 

• An output class for all high-priority printed output, 
or for printed output requiring special forms. 

• An output class for all punched output. 

• An output class for all output to magnetic tape. 
By specifying the appropriate output class in the dd 

statement, the programmer selects the particular de- 
vice on which his output is to be recorded. Because 
writers can share output classes, a writer can have a 
primary and a secondary function. For example, if 
output class B is assigned to a high-priority printer, 
and output class C to a "background" printer, the high- 
priority printer processes only high-priority output 
(sysout=b). 

If no high-priority data is waiting on the output 
work queue, the output writer performs its secondary 
function by taking a job from the sysout=c queue. 
The advantage in this use of multiple writers is not 
only that it makes writers available for certain types 
of unique work, but that it also permits them to per- 
form other work when circumstances permit. 

Note: Problem programs can access SYSOUT data sets only 
through BSAM and QSAM. They can no longer access them 
using EXCP. 



Avoiding System Interlocks 

A problem can occur when a task controls a resource, 
but is waiting for another resource which is under con- 
trol of a second task. If the second task is waiting, and 
needs the resource now under control of the first task, 
a system interlock condition will occur. The first task 
cannot give up its resource until the second task re- 
linquishes the resource it controls, and vice versa. The 
two tasks are therefore in a deadlock; processing can- 
not continue in either partition. 

Two ways to avoid this problem are: 

1. Request all resources initially; do not begin an ir- 
reversible course of action until all required re- 
sources have been obtained. 

2. If the program is holding a formerly obtained re- 
source which may prevent acquisition of another 
resource, release the resource before requesting the 
other resource(s). If the former resource is still re- 
quired, request it together with the other resource(s). 



Data Set Integrity 

An interlock may also occur during job initiation, if a 
job requests one or more data sets which are reserved 
for use by another job which is currently executing in 
the system. In order to prevent this interlock, the oper- 
ator is notified of the condition through a series of 
console messages. The operator must then make a 
decision, based on his knowledge of the jobs in the 
system, the system configuration, and the data sets in 
use. He may wait for the requested data set(s) to 
become available, he may place the job on the hold 
queue, or he may cancel the job being initiated. 
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Batch Processing 

If the installation's work is primarily batch jobs, several 
factors must be considered when the system is initi- 
alized, and when it is operating. First, the number, 
size, and job class ( es ) for each partition must be deter- 
mined. Then the decision must be made as to which 
partitions, if any, should contain direct system output 
writers. The proper output classes for the installation 
must also be determined. 



Choosing Number and Size of Partitions 

The number and size of partitions depends on the 
amount of real and virtual storage available in the 
system and on any virtual=real requirements that may 
exist for specific jobs. The best configuration for a par- 
ticular installation usually depends on the type of job 
most frequently run. 

Assigning Job Classes to Jobs 

Every job should be assigned a job class, using the 
CLASS parameter. For batch processing of input/ output- 
limited jobs, each job should be assigned a job class 
that corresponds to a high-priority partition. Process- 
limited jobs should be assigned to a lower-priority par- 
tition. In addition, jobs that can be executed without 
having any special input/ output setups (that is, "non- 
setup" jobs such as a fortban compiler), or that have 
preallocated data sets, can be directed to a high- 
priority partition for fast throughput. 

Assigning Partitions to Job Classes 

A £4- — 4-U„ :^U ^1 U^,,„ U ,• ^A 4-^ ,-^U^ ^^ 

propriate partitions must be assigned to service those 
jobs. If the partitions do not have the appropriate job 
classes specified, the job classes can be changed (see 
Partition Redefinition in the Concepts section), or the 
CLASS parameter can be changed on the job card, be- 
fore the job is entered in the input stream. 



Choosing Output Classes 

At an installation it may be advisable to set up certain 
output classes for specific duties. For example, output 
class A could be for system messages, and class B for 
problem program output. Or, class A could be for sys- 
tem messages, class B for problem program output 
for the accounting department, class C for problem 
program output for the purchasing department, etc. 

Note: System messages are assigned an output class through 
the MSGCLASS parameter on a JOB card. Problem program 
output is assigned an output class through the SYSOUT param- 
eter on a DD card. 

Another approach would be one in which output 

class A represents printer system message output, class 

B represents punched card output, class C represents 

problem program output. Up to 36 output classes may 
be specified. When using special forms on the printer, 
the operator should ensure that system messages are 
not written on the special forms. This possibility can 
be eliminated by establishing a different output class 
for output requiring the special forms. 

Note: An identification problem may arise if system messages 
are assigned an output class different from problem program 
output. Therefore, it may be helpful for the programmer to 
print, as the first line of output, his name and department, if he 
chooses to use different classes for message and problem pro- 
gram output. This would also alleviate some operator problems. 
(See Operating Considerations in this section.) 

When the system log option is present, system log 
data sets must be assigned an output class. The assign- 
ment can be made at system generation by using the 
WTLCLSS operand of the schedulr macro instruction. 
Two log data sets are provided for recording the data 
sent to the log. To avoid the situation where the second 
data set becomes full before the first data set can be 
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writer class must be considered at system generation. 
To be sure that a full log data set is processed in a 
reasonable period of time, a imique output message 
class should be assigned for the log data sets and a 
writer should be assigned multiple output classes with 
the log class having the highest priority. 
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Telecommunications 

vsi enables telecommunications jobs to be run con- 
currently with other types of jobs such as batch, 
graphics, and concurrent peripheral operation (cpo). 
Several vsi considerations are of interest to the tele- 
communications user. 

These considerations include the number of telecom- 
munications partitions required, their placement in the 
system, their size, and their job class (es). 

Choosing Number and Size of Partitions 

Telecommunications jobs are considered unending in 
that they are scheduled only once, and are terminated 
only when a cancel command is entered, that is, for 
partition redefinition. ( See Partition Redefinition in the 
Concepts section. ) There must be at least one partition 
for each telecommunication job being run. The size of 
the partition depends upon the size of the telecom- 
munications control program used by the installation. 
To avoid delays in servicing lines, a telecommuni- 
cations job should have unrestricted access to the re- 
sources of the central processor. For this reason, it is 
best to run telecommunications jobs in high-priroity 
partitions. Because the telecommunications job is not 
alone in the system, its activities should cause mini- 
mum interference with jobs in other partitions, and it 
should not be susceptible to interference from these 
other jobs. 

Assigning Job Classes to Jobs 

Each telecommunications job should have a unique 
job class assigned to it. The message control partition 
(PO) should have a difiFerent job class from the mes- 
sage processing partition. Caution must be taken to 



avoid assigning job classes to problem programs that 
correspond to the job class(es) of the telecommuni- 
cations partitions. Caution must also be taken to assure 
that all telecommunications jobs are assigned class 
parameters corresponding to those defined for the 
high-priority teleprocessing partitions in the system. 

Assigning Partitions to Job Classes 

Each telecommunications partition should also have a 
unique job class so that the appropriate jobs may be 
directed to that partition. If the job classes are to be 
changed, a cancel command must first be entered 
to terminate the unending job, and then the system 
may be redefined. (See Partition Redefinition in the 
Concepts section. ) Likewise, if the partition is not as- 
signed to the telecommunications job class, the tele- 
communications job may never be initiated. 

VSI Telecommunications Compatibility 

vsi BTAM ( Basic Telecommunications Access Method ) 
and VSI tcam (Telecommunications Access Method) 
are the same externally as their equivalents in os. Both 
types of programs will run, without modification, in the 
VSI environment after reassembly. The reassembly al- 
lows the existing programs to benefit from the virtual 
storage feature of vsi. The user is cautioned that if any 
internal changes have been made to either os btam 
or OS tcam to tailor them for a particular need, similar 
changes must be made to the vsi versions to retain 
their compatibility. For more information about btam, 
refer to OS/VS Basic Telecommunications Access 
Method, GC27-6980. For more information about 
TCAM, refer to OS TCAM Concepts and Facilities, 
GC30-2022, and OS/VS TCAM Programmers Guide, 
GC30-2034. 
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Graphics 

Graphic jobs in a vsi environment are subject to sev- 
eral general considerations. A graphics job associ- 
ated with an unbuffered ibm 2250 Display Unit may 
operate with reduced performance if high telecom- 
munications activity interferes with its access to the 
central processor for regenerating the display. In this 
case the relative importance of the graphics and tele- 
communications jobs must be determined, and the de- 
cision made as to which to run in the higher-priority 
partition. Additional considerations for vsi include 
assigning job classes to jobs, choosing the partition to 
service graphics jobs, using the time-slicing option, and 
assigning partitions to job classes. 

Choosing Number and Size of Partitions 

There must be at least one partition for each graphics 
job being run. The partition size depends upon the size 
of the graphics job. Generally, graphics jobs should be 
run in a high-priority partition to cause minimum 
interference with other jobs. If telecommunications 
and graphics are being run in the same system, the 
best performance would be gained by placing the tele- 
communications job in a high-priority problem pro- 
gram partition, and the graphics job in a relatively 
high-priority partition also. 

Assigning Job Classes to Jobs 

Graphics jobs should have a unique job class assigned 
to them, to ensure that they are executed in the se- 
lected partition. 

Assigning Partitions to Job Classes 

A graphics partition should be assigned a unique job 
class that corresponds to the job classes assigned to the 
graphics jobs. This ensures that jobs will be enqueued 
on the proper input queue, and executed in the appro- 



priate partition. The partition could also be assigned 
secondary and tertiary job classes to reduce idle time. 
If the partition's job class is to be changed, and a 
graphics job is being run, a cancel command must be 
issued for the graphics job, and then the partition may 
be redefined. 



Using the Time-Slicing Feature 

The time-slicing feature of assigning uniform intervals 
of CPU time to a group of consecutive partitions is pro- 
vided at system generation. (The number of time- 
slicing partitions and the time interval for each task 
are specified in the tmslice parameter of the ctelprog 
macro instruction. ) The ability to get uniform response 
time is useful in a graphics environment, particularly 
for concurrent applications involving graphics ter- 
minals. To minimize contention for the cpu with other 
jobs, it is best to establish the higher-priority partitions 
as time-slicing partitions. 



Graphics Support with VSI 

The Graphic Subroutine Package (gsp) provides ibm 
2250 graphics support for pl/i, Fortran, and cobol f 
and is externally equivalent to os imft Release 21.0. 

The Graphics Access Method (gam) provides sup- 
port for the IBM 2250 and ibm 2260 display units and 
is externally equivalent to os mft Release 21.0. 

For more information about gsp, refer to the OS/VS 
Graphic Subroutine Package (GSP) for FORTRAN IV, 
COROL, and PL/I, GG27-6973. For more information 
about gam, refer to the OS/VS Graphic Programming 
Services (GPS) for the IRM 2250 Display Unit, GC27- 
6971, and to the OS/VS Graphic Programming Services 
(GPS) for the IRM 226G Display Siation (Local At- 
tachment), GC27-6972. 
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Concurrent Peripheral Operations 

Concurrent Peripheral Operation (cpo) is the capa- 
bility of performing utility functions such as card-to- 
tape, tape-to-print, or tape-to-punch while other jobs 
in the system continue processing. Execution of cpo 
jobs in vsi involves the same general considerations 
for assigning job classes to jobs and partitions as for 
telecommunications and graphics jobs, cpo jobs should 
be assigned a class that corresponds to that of the cpo 
partitions. The cpo partition should be assigned a job 
class different than that for any other partition. 



Typical System Configurations 

This topic describes partition configurations for sys- 
tems with 128K, 192K and 384K bytes of real storage. 
These configurations are based on the considerations 
presented in the preceding four topics. Working con- 
figurations will depend on the individual requirements 
of each installation. The values for virtual=real areas 
shown in these configurations do not represent the 
actual size of the space available for v=r jobs. This is 
due to dynamic allocation of real storage by the system. 
See the Storage Estimates publication for estimates of 
the actual space requirements for any specific config- 
uration. 



Note: In Figures 22-25, do not assume that the portions of 
real storage above (to the right of) SQA space exist as shown 
in the figure; pages of JES, problem programs, etc., may be 
scattered throughout the available real storage. Also, this area 
above the SQA space includes the 36K reserved by the system 
(see the earlier topic Virtual=Real Storage Availability). 



Systems with 128K Real Storage 

A 128K system can support one configuration. The two 
parts of Figure 22 show possible storage configurations, 
real and virtual, for a minimum system, and illustrate 
the relationship of real and virtual storage. 

Systems with 192K Real Storage 

A 192K system makes possible a variety of configura- 
tions. Depending on the requirements of the installa- 
tion, the most likely configurations will include two 
large (128K or larger) batch partitions, or three or 
four smaller (64K or larger) batch partitions. Tn either 
case, several system output writers could be provided 
to support the batch partitions. Figure 23 illustrates 
the first case, with two large batch partitions. 

Systems with 384K Real Storage 

The choice of configurations available with 384K bytes 
of real storage is so great that no "typical" system can 
be defined. Figure 24 shows a possible configuration 
with five batch partitions. 

Figure 25 shows a possible configuration with a tele- 
processing job running with four batch partitions of 
varying sizes. 

Operating Considerations 

The operator of a vsi system must be aware of sev- 
eral considerations related primarily to program execu- 
tion, partition definition, output class reassignment, 
restarting the system, and operator commands. If the 
system has the shared dasd option, the operator must 
also consider shared volume handling. These consid- 
erations are explained in the following paragraphs. 




Figure 22. Storage Configurations for 128K System 
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Figure 23. Storage Configurations for a 192K System 
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Figure 24. Storage Configurations for a 384K System 



Program Execution 

Because 15 problem programs can be executed con- 
currently, the system places additional responsibility 
on the vsi operator. At times he may become busy 
replying to system messages and problem program 
messages, placing special forms in the printer, etc. 
Therefore, whenever possible, he should perform pre- 



paratory work, such as obtaining and/ or mounting 
required volumes, ahead of the required time. When 
responding to problem program messages, the operator 
should respond to the highest priority task first; that is, 
the message from the partition with the lowest num- 
ber. The operator must also remember that problem 
program and system messages may be intermingled on 
the console device. 
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Figure 25. Storage Configurations for Teleprocessing and Batch Processint 



In addition, because jobs may not be completed in 
the same order as they were entered in the system, the 
operator must ensure that the correct output is re- 
turned to each programmer. 

The operator may also be required to start system 
input readers and output writers at certain times dur- 
ing operation. He may be given a specific time each 
day, or may have to use his judgment based on work 
load for the system. 

Partition Definition 

Even th( the installation may not intend to use the 

maximu lUmber o£ partitions at all times, the system 
must be regenerated if the number of partitions origi- 
nally specified is increased. Therefore, the maximum 
number of partitions expected to be used should be 
specified at system generation. Partitions can then be 
redefined to decrease the number in use. 

Caution must be observed when redefining parti- 
tions. Before redefining partitions, the operator should 
check the job class ( es ) of all pending jobs and ensure 
that the prospective partition definitions have job 
classes corresponding to the jobs that will be executed. 
This includes knowing the job classes of jobs which 
have already been placed on the input or hold queues, 
but have not been executed. (This can be accom- 
plished by issuing the display q command.) If pos- 
sible, he should also check pending jobs for their size 
requirement ( by checking the job class versus the size 
of the partition assigned to service that job class) and 
compare this with the size of the job partitions. If they 



are originally assigned a class parameter that corre- 
sponds only to a large partition, they should be re- 
assigned to a large partition. 

If the time-slicing feature is included in the system, 
the operator should not specify the same job class for 
both a time-sliced partition and a partition that is not 
time-sliced. For example, do not specify a partition 
with job classes B, C, D in a time-sliced group, and a 
partition with job classes D,E,F outside the group. 
Doing so would allow a job with a class parameter of 
D to be executed either inside or outside the time- 
shced group regardless of the programmer's intentions 
for that job. Also, a partition in a time-sliced group 
should not be assigned to service jobs with job classes 
of A, because A is the default job class, and the same 
problem could arise. 

After all redefinitions have been completed, message 
IEF805I DEFINITION COMPLETED' is issucd. The Operator 
must enter either a start init command for each of the 
partitions that have been redefined, or a start init. 
ALL command. 

Partition Deactivation/Reactivation 

This function enables the operator to declare a parti- 
tion eligible or ineligible for deactivation, or to reac- 
tivate any deactivated partition. The function is 
available at ipl time and, through the use of the de- 
fine command, after ipl. The operator may display 
the current status of the partitions by using the list 
option of the define command, or by using the dis- 
play A command. 
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At nucleus initialization time, the operator can vary 
the function of timed task reactivation by responding 
to message ieaioia specify system and/ or set paea- 
METERS FOR RELEASE xx.yy.sss with the keyword 
REACT =d. d is a decimal digit from — 9, the number 
of seconds for the timed interval. The value is used by 
the page supervisor at system wait time in an attempt 
to reactivate the highest priority partition currently 
deactivated. Task reactivation is executed when the 
specified time interval has elapsed, the paging rate has 
diminished to zero, and sufficient real storage has be- 
come available to reinstate the deactivated task. The 
fewer the number of seconds used for the interval, the 
more likely a partition may become reactivated. How- 
ever, the availability of real storage space for pages is 
still the prime prerequisite for reactivation. 

If REACT=d is not specified, deactivation/ reaction 
works as follows: 

• When a partition is deactivated, the time elapsed 
since the last reactivation is used to set a delay 
interval. When that interval elapses, the zero page- 
rate interval is set. This second interval is deter- 
mined by the number of active tasks. When no pag- 
ing for the zero page-rate interval has occurred, and 
enough real storage is available, the highest priority 
task is reactivated. The delay interval is reset to its 
maximum value, determined by the real storage 
size. 

Though the operator can declare any partition in- 
eligible for deactivation, he should exercise care in the 
selection. A problem program partition should be de- 
clared ineHgible for deactivation only if activity within 
that partition is judged to be critical to the process- 
ing environment. For example, if a user-written tele- 
processing application was deactivated (by the page 
supervisor), the user's entire teleprocessing network 
might fail. 

Whenever the system operator reinstates a currently 
deactivated job, time should be the only criterion in the 
decision. For example, a job such as a payroll run 
might have to be "rushed" through the system. When- 
ever such a decision is made, other active tasks should 
be eligible for deactivation. If this is not done, the 
amount of real storage available for paging may be 
decreased to such a low level that the currently active 
partitions cause the system to run inefficiently. That is, 
each active task requires pages for itself, which in turn 
causes another task to begin paging, and so forth. This 
condition is called "thrashing". For aU practical pur- 
poses, a system that is thrashing is running only the 
page supervisor task. 

When the operator determines that a partition has 
been deactivated for a relatively long period of time, 
several actions are available: 



• He can specify that the deactivated partition be 
reactivated for the duration of the job executing in 
that partition. At job completion, the partition is 
then elegible for deactivation should a shortage of 
pages develop again. 

• He can put a hold on the job queue. As jobs in the 
active partitions end, the deactivated partitions can 
become active and complete their tasks. The queue 
can then be released and processing can continue. 

• He can stop an active partition. Assuming that 
stopping the partition reduces the paging activity, 
the results would be comparable to putting a hold 
on the job queue. 

• He can cancel the job in the deactivated partition, 
stop the partition, and re-enter the job in the job 
queue where it can be selected by another partition. 

Regardless of what technique is used, it is imperative 
to remember that the partition was deactivated because 
its activity was detrimental to the system as a whole. 
With this in mind, it would be wise in most cases to 
stop a deactivated partition after applying one of the 
preceding methods. 

For specifying partition eligibility for deactivation 
and reactivation, see message iee802A and message 
IEE803A in the OS/VS System Messages publication. 
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The output classes with which a writer is associated 
can be changed at any time, through proper use of the 
MODIFY command, or a combination of stop and start 
commands. A program with a special forms require- 
ment can obtain exclusive use of a printer by informing 
the operator to enter a modify command. A stop com- 
mand followed by a start command for the same 
writer, but soecifvinff a uniaue outDut class, could also 

J. ^ O J. J. 

be entered. The stop command causes the writer to 
stop at the end of the job it is currently executing. The 
operator then inserts the required forms and issues the 
new start command. That command would limit use 
of the printer to the data set associated with the new 
output class until another stop and start command 
sequence for the printer is issued. The modify com- 
mand can also be used to change the conditions under 
which the output writer pauses for servicing of its 
device. 

For example, a writer named one, originally estab- 
lished to service output classes A, B, and C, could be 
changed to service only data sets for output class D by 
issuing the command: 

MODIFY WTR.ONE,CLASS = D 

Handling Shared Direct Access Volumes 

If the shared dasd feature is selected at system genera- 
tion, additional responsibilities are imposed on the 
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operator. Volume mounting and dismounting instruc- 
tions are normally issued by the operating system. In 
a shared dasd environment, volume handling must be 
initiated by the operator and must be conducted in 
parallel on both sharing systems. Thus thorough oper- 
ator communication from system to system must be 
maintained. 



Restarting the System 

To restart the system after it has been shut down, the 
same steps taken in initially starting the system are 
followed, except when the set command is entered. 
Either the "F" suffix from the "Q=(unitname, [F])" 
parameter is omitted, or the entire "Q= " parameter 
is omitted. 
The following command illustrates this procedure: 

SET DATE=yy.ddd,CLOCK=hh.mm.ss 

By omitting the "Q= " parameter, job queue data set 
information is saved. When restarting the system to 
save the information, the operator must make certain 
that all auxiliary storage volumes which were in use 
remain available. This ensures that the job queue data 
set, spool data sets, and swads data sets accurately 



reflect the conditions which existed when a restart be- 
came necessary. 

Operator Commands 

The following commands, and their respective abbrev- 
iations, may be used in a vsi system: 



CANCEL 


C 


RELEASE 


A 


CONTROL 


K 


REPLY 


R 


DEFINE 


N 


RESET 


E 


DISPLAY 


D 


SET 


T 


DUMP 




START 


S 


HALT 


Z 


STOP 


P 


HOLD 


H 


STOPMN 


PM 


LOG 


L 


SWAP 


G 


MODE 




SWITCH 


I 


MODIFY 


F 


UNLOAD 


U 


MONITOR 


MN 


VARY 


V 


MOUNT 


M 


WRITER 


WTR 


MSGRT 


MR 


WRITELOG 


W 



Note: The commands are subject to the following restrictions: 

• The DEFINE, HALT, MODE, SWAP, and WRITER 
commands are not allowed in the input stream; they must 
be entered through a console. 

• The DUMP and MODE commands cannot be abbreviated. 
Be sure to use the correct abbreviations for operator 

commands. For example, at system initialization, if you 
inadvertently key in S for set, the system assumes you 
are giving a start command. It queues the command, 
and waits for a set command. 



52 OS/ VSI Planning and Use Guide 



The Use Guide 

The Use Guide contains sections covering the following topics: 

Handling Accounting Information 

Automated System Initialization 

OS/MFT-OS/VSl Differences 

VSl Features and Options 

JES Reconfigurability 

Job Queue Format 

Message Routing Exit Routines 

The Must-Complete Function 

The PRESRES Volume Characteristics List 

System Reader, Initiator, and Writer Cataloged Procedures 

Resident Routines Option 

Output Separation 

The Shared Direct Access Device Option 

System Macro Instructions 

Adding SVC Routines to the Control Program 

How to Use the Tracing Routine 

The Time Slicing Facility 

Writing System Output Writer Routines 

Appendix A: Theory of Operations 

Glossary 

Publication References Reference is made in the Use Guide to other os/vs pubHcations. These references 

do not include the complete tide and order number of the publication. To 
facilitate use of this publication, complete titles and order numbers of the 
referenced books are indicated here. 

OS/VS Data Management Services Guide GC26-3783 

OS/VS Data Management Macro Instructions GC26-3793 

OS/VS JCL Reference GC28-0618 

OS/VS Message Library Publications 

VSl System Messages GC38-1001 

System Codes GC38-1003 

Routing and Descriptor Codes GC38-1004 

Operator's Library Publications 

OS/VSl Reference GC38-0110 

OS/VS Console Configurations GC38-0120 

I OS/VSl RES System Programmers Guide GC28-6878 

OS/VS Service Aids GC28-0633 

OS/VSl Storage Estimates GC24-5094 

OS/VS Supervisor Services and Macro Instructions GC27-6979 

OS/VSl System Data Areas SY28-0605 

OS/VS System Generation Introduction GC26-3790 

OS/VSl System Generation Reference GC26-3791 

OS/VS Utilities GC35-0005 
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Conventions used in 
Illustrations of Coding 

Certain conventions are used to illustrate the format 
of macro instructions included in this publication. 
These conventions are: 

• Letters in capitals, numbers, and punctuation marks 
(except as noted below) must be coded exactly as 
shown. 

• Brackets, [ ]; braces, () ; ellipses, . . .; and sub- 
scripts are never coded. 

• Lowercase letters represent variables for which you 
must substitute specific information or specific 
values. 

• Items or groups of items within brackets are op- 
tional. They may be omitted at your discretion. 
Conversely, the lack of brackets indicates that an 
item or group of items must be coded. 

• Stacked items enclosed in braces represent altern- 
ative items. Only one of the stacked items should 
be coded. 

• If an alternative item is underlined, it is the de- 
fault value. The system will automatically assume 
it is your choice if none of the items is coded. 

• An ellipsis indicates that the preceding item or 
group can be coded two or more times in succes- 
sion. 
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Handling Accounting Information 



You may add accounting facilities to your vsl opera- 
ting system. This section describes the input avail- 
able to an accounting routine; the characteristics and 
requirements of an iBM-supplied data set writer that 
may be used to log accounting information generated 
by an accounting routine; and how to insert an ac- 
counting routine into the control program. Conven- 
tions to be followed in preparing an accounting rou- 
tine are also noted. 



Section Outline 
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Accounting Routines 



Your installation may prepare accounting routines for insertion in your vsl 
operating system. These routines are inserted in the control program during, or 
after, system generation. 



Prerequisite Actions 



At system generation you must specify that an accounting routine is to be 
supplied. This is done through the SMF=parameter of the system generation 
SCHEDULR macro instruction. 



This specification causes the linkage to your accounting routine to be installed 
in the scheduler component of the system being generated, and makes usable the 
accounting data set writer routine. If you are not going to install your accounting 
routine until after the system is generated, a dummy accounting routine (named 
iefactrt) is also placed in the system at this time. Insertion of accounting 
routines in the control program is discussed later in this section. 



Accounting Routine Conventions 



Format 



Your accounting routine may consist of one or more control sections. 



Attribute 



An accounting routine written for insertion in your vsl operating system must 
be serially reusable. 



CSECT Name and Entry The contiol section containing the entry point of your accounting routine, and 

Pomt the entry point, must be named iefactrt. 



Register Saving and 
Restoring 



The content of registers through 14 must be saved upon entry to your ac- 
counting routine and restored prior to exiting. 



Entrances 



Control is given to your accounting routine at the following times: 

• Step initiation 

• Step termination 

• Job termination 



Exit 



You can use the return macro instruction to restore the contents of the general 
registers and return control to the operating system. 
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Input Available fo Accounting Routines 



Register contains an entrance code, indicating at what time the accounting 
routine is being given control. 

Register = 8: Step initiation 

= 12: Step termination 
= 16: Job termination 
Register 1 contains the starting address of a list of pointers to items of accoimt- 
ing information. Each pointer is on a fuUword boundary. The sequence of 
pointers in the list and the items of information provided are described in Figure 
ACC 1. 

User accounting routines should only use pointers that are in the list addressed 
by register 1. Other pointers are subject to change in subsequent releases. 



Output from Accounting Routines 



You can write output in three ways: by issuing console messages; by using the 
standard system output; by using an iBM-supplied accounting data set writer. 

1. Console messages— You can use write to operator (wto) or write to operator 
with reply (wtor) macro instructions. 

2, System output— Assemble the following calling sequence into your routine. 
The contents of register 12 must be the same as when your accounting 
routine was entered, and register 13 must contain the address of an area 
of 32 fuUwords. 

When viTiting an accounting routine for inclusion in the job scheduler, 
you must be aware that register saving conventions within the control pro- 
gram are different from those for problem programs. In the job scheduler, 
registers are saved in the sequence 14-12 in a 15-word save area. There 
is no place provided to save register 13. You must provide some other means 
of saving register 13; you may either save it in another register or provide 
an additional save area that is not known to the control program. This can 
be done by adding a word to the end of the save area that is provided 
and is addressed as save -f- 60. 



Name 


Operation 


Operand | 




MVC 


36(4, 12), MSGADDR 


MOVE MESSAGE ADDRESS 




MVC 


42(2, 12), MSGLEN 


AND LENGTH TO SYSTEM 




L 


REG15, VCONYS 


TABLE BRANCH AND LINK 




BALR 


REG14, REG15 


TO MESSAGE ROUTINE 


MSGADDR 


DC 


A (MSG) 




MSG 


DC 


C'text of message' 




MSGLEN 


DC 


H 'two character length 


of message' 


VCONYS 


DC 


V(IEFYS) 





3. Accounting data set writer— This writer places accounting records you have 
constructed in your accounting routine in a data set named sysI.acct. The 
data set must reside on a permanently resident direct access device. You 
must provide, in your accounting routine, linkage to the writer, and pass 
the beginning address of the record to be written, to it. Use of the data 
set writer is covered later in this section. 
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Byte 



Byte 






Job Name 
Pointer 




1 ' 




Job Name 
8 Bytes 



Byte 



4 


Step Name 
Pointer 




' ' 




Step Name 
8 Bytes 



Byte 



8 


Programmer 
Name Pointer 




' ' 




Programmer 
Name 20 Bytes 



12 


Job Running 
Time Pointer 




' ' 




Job Running Time 
3 Bytes 


Pointer + 3 • - 




Entry Count 1 Byte 



Byte 



The step name pointer is zero at job 
termination 



A riglit justified binary number represents 

job running time in hundredths (0.01) of a 

second. 

If a programmer deferred restart occurs, the 

time used during the original execution is 

omitted from the job time passed to a user 

routine. 

The entry count byte contains the number 

of job accounting entries picked up from 

the JOB statement. Commas used to denote 

omitted entries are counted. 



16 


Job Accounting 
Data Fields 
Pointer 














1 
or ' 










00 




A byte of zeros indicates that the JOB 




' 








statement did not contain accounting in 




Byte 
Count 


I Data 


Byte 
Count 


Data 




Byte ' 

Count . Data 
n 1 n 


00 



These data fields contain the accounting information that was specified in the JOB statement. The first byte of each field 

contains the number of bytes of data that follow. The last data field is followed by a byte of zeros. 

.A data field — consisting only of the first, or count byte, is developed for an omitted accounting entry. The byte contains 

zeros, indicating that no data is present for that field. In this case: 

When (a, b„ d) appears in the JOB statement 



Byte , 

Count I Data 
a , s 



Byte 
Count, 



bl °^'% 



00 



Byte 
Count 



d I °''^d 



00 



Byte 



Note: Use the entry-count byte (job running time pointer + 3) to determine if you have processed all the accounting 
data fields. 



The step running time pointer is zero at job termination. 

The step running time is not on a full word boundary. A binary number, right justified, 
represents step running time in hundredths (0.01) of a second. 

If an automatic restart occurs, the system gives control to a user routine prior to restarting; step 
time passed is the time used by the step. Upon successful completion of a step that was auto- 
matically restarted, the step time passed to a user routine does not include the time used by the 
step during its original execution. If a programmer deferred restart occurs, the time used during 
the original execution is not included in the step time passed to a user routine. 
Number of step accounting entries picked up from the EXEC statement. Commas used to 
denote omitted entries are counted. 



20 


Step Running 
Time Pointer 




1 


' 




Step Running Time 
3 Bytes 


Pointer + 3 i 


r 




Entry Count 1 Byte 



Byte 



24 



Step Accounting 
Data Fields 
Pointer 



This pointer is 
zero at job 
termination 



The step accounting data fields conform 
to the same specifications as the job ac- 
counting data fields. 



Byte 






28 


"Flags" and Step 
Number Pointer 






Pointer + 1 ■ 






"Flags" Byte 




' 




Step Number Byte 



Setting bit 7 of this byte to 1 effects job 
Cancellation. 

This byte contains the number of the job 
step currently being processed. The first 
step in the job is 1. 



Note: You can use the flag byte to cancel the execution of a job whose accounting information does not conform to your installation's 
standards. You can equate step initiation for the first step in a job to job initiation, i.e., the step number byte contains 1 . 



Figure ACC 1. Accounting Information Available to User 
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Sample Accounting Routine 



A sample accounting routine, showing use of the data set writer, output to 
system output, and issuance of console messages, is stored under the member 
name samactrt in the sysI.samplib data set furnished with the starter operating 
system. 



Inserting an Accounting Routine into the Control Program 



Your accounting routine can be inserted in the control program in two ways; 
by placing the routine on the sysI.aosOO data set used in system generation 
or by placing the routine in the appropriate load module of the control program 
after system generation. The effect of either action is to replace a dummy ac- 
counting routine with your accounting routine. 



Insertion at System 
Generation 



To insert your accounting routine into the control program during system genera- 
tion, you must, prior to the start of the system generation process, place your 
routine in the sysI.aosOO data set, using the linkage editor. The sysI.aosOO data 
set (furnished with the starter operating system) contains load modules which 
are combined during the system generation process to form the load modules 
composing the control program. In response to the specification made in the 
system generation schedulr macro instruction, your accounting routine is in- 
corporated in the appropriate load modules for the system being generated. 

You must place your accounting routine in the sysI.aosOO data set under the 
name iefactrt. You will be replacing the dummy accounting routine— also 
named iefactrt. 



insertion after System 
Generation 



To insert your accounting routine into the control program after system genera- 
tion you place the routine in load modules of the scheduler component of the 
generated control program, using the linkage editor. The scheduler load modules 
are in the linkage library (sysI.linklib data set) of the generated system. The 
affected load modules are as follows: 

load module iefw21sd— step initiation 

load module iefsd161— step/job termination 

An example of the input for a linkage editor run to insert your accounting 
routine into the job scheduler follows: 



//jobname 

//stepname 

//SYSPRINT 

//SYSUTl 

//SYSLMOD 

//SYSLIN 



JOB 

EXEC 

DD 

DD 

DD 

DD 



( parameters ) 

PGM=:IEWL, (parameters) 
SYSOUT=A 

UNIT=SYSDA,SPACE= ( parameters ) 
DSNAME=SYS1.LINKLIB,DISP=0LD 



(object code) 



INCLUDE 
ALIAS 

ENTRY 

NAME 



This sequence must be 
repeated for each 
scheduler load module 
into which you wish 
to insert accounting 

SYSLMOD (load module name) routines. 

alias names 

entry point name 

load module name(R) 
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In this example "load module name" represents the appropriate scheduler load 
module as identified in the preceding text. To ensure accuracy in identifying 
the correct alias names and entry point names for the load modules, obtain these 
names from the system generation listing produced during generation of the 
system you are working with. These names are specified in the system genera- 
tion Stage II linkage editor output for the linkage editor execution that produced 
the load module. 



Accounting Data Set Writer 



The accounting data set writer (module iefwad) is inserted in the appropriate 
scheduler load modules during system generation when accounting routine in- 
clusion is specified in the schedule macro instruction. These are the same 
modules in which your accounting routine is inserted. Scheduler storage re- 
quirements are increased by the amount of storage needed by your accounting 
routine plus 2600 bytes. The writer places accounting records developed by 
your routine in a data set named sysI.acct. 



Linkage Your accounting routine links to the writer via the following mechanism: 

L R15,VCON 

BALR 14,15 



VCON DC V( IEFWAD) 



Input Your accounting routine passes in register 1 the address of the accounting record 

to be written. 

The record format is: 

DS 3H — space used by the data set writer 

DC H' — ' — contains the number of bytes of data being passed. This number 
cannot exceed the capacity of 1 track on the direct access volume 
being written on. 

DC — the data to be written in sysI.acct. 

Registers 13, 14, and 15 are used as specified by operating system conventions 
(14 and 15 are used for linkage, as previously shown; 13 must point to an 
18-word save area). 



Specifying the SYSI.ACCT The sysI.acct data set must be pre-allocated on a direct access volume that will 
Data Set be permanently resident. The data set must be named sysI.acct, have no secon- 

dary extents, and be allocated contiguous space. Do not catalog the data set. 

If your installation has two permanently resident volumes available for ac- 
counting routine use, you may create two sysI.acct data sets and utilize the 
console messages and replies to notify the system of the data set to be addressed. 
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Output 



If the lEFWAD routine successjfully writes your record in the sysI.acct data set, 
the routine returns control to your accounting routine immediately. If the 
routine fails to write your record, it uses message ief507d to bring the error 
condition to the attention of the operator. ( See the appropriate OS/VS Messages 
Library publication for the text of, and answers to the message.) Depending 
upon his answer, the routine may try again to write your record in the sysI.acxtt 
data set. 

In any case, a code is returned to your routine indicating either that the 
record was written successfully, or, if it was not written successfully, the cause 
of the failure. The return codes are described in the following: 



Contents 


Type 


Meaning 1 


Register 15 | 





D 


The record was written to the data set. 


4 


D 


The record was not written to the data set because the record 
exceeds the length of one traci<. 


8 


D 


The record was not written to the data set because there is no 
more space in the data set. 


12 


D 


The record was not written to the data set because no space 
had been allocated to the data set. 


16 


D 


The record was not written to the data set because a perma- 
nent I/O error was encountered while trying to write it. 


20 


D 


The record was not written to the data set because the 
previously last record could not be found. 


24 


D 


Operator gave invalid device address. 


Register | 


n 


B 


Number of tracks still available in the data set. (Valid only if 
register 15 is zero.) 


Type - Type of number: D — Decimal, B — Binary 



Use of ENQ/DEQ 



lEFWAD enqueues on the major queue name sysiefsd and the minor queue name 

WD. 
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Automated System Initialization 



This section describes the use of the automated system 
initialization featm'e. This feature makes the system 
initiaHzation process quick and flexible through the 
use of SYsl.PAEMLiB data set members to hold sys- 
tem initialization parameters. Use of this feature sig- 
nificantly reduces the operator's role in the initializa- 
tion process. 



Note: The term initialization here refers to the period begin- 
ning when the IPL program is loaded and ending when the 
system is ready to perform meaningful work for the user. It 
involves all responses and commands issued by the operator 
until the system is initialized. 
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Advantages of Automated System Initialization 

Automated system initialization is a standard feature available for use at your 
convenience. It requires no changes in system generation options and provides 
the following advantages over the other procedures, which involve the operator's 
making lengthy entries on the system console: 

• The responsibility of altering the system is placed directly on the system 
programmer. 

• The flexibility of keeping system initialization parameters in sysI.paemlib 
members permits each sj^stem initialization to be a tailoring process that en- 
ables the system to better meet the needs of the anticipated job mixture. 

• The time needed for initialization is reduced. 

® The operator's role is reduced, thus freeing him to do other tasks. 

• The operator may see only one entry across systems, thus eliminating con- 

4nc;irv^ rt\ri^'r \T7hi/-ih cv"?^"'^■•^^ iQ r»<^innr -itrifip ii'jorl 

• Informational messages not critical to the operator can be eliminated until 
the initialization is complete. 

• Redefinition of partition sizes, job classes, and time slicing can be done with 
a minimum of operator involvement. 

The Automated System Initialization Process 

Use of automated system initialization involves first the creation of members in 
sysLpaemlib and then the processing of these members by the nucleus initializa- 
tion program (nip) and the master scheduler initialization (msi) program: 



Process 


Comments 


Before Initialization 

System programmer creates initializa- 
tion members in SYS1 PARMLIB by 
using tiie lEBUPDTE utility. 


Naming conventions must be followed. 


At initialization 

NIP request operator to "SPECIFY 
SYSTEM AND/OR SET 
PARAMETERS". 

NIP uses the entries in the list to modify 

the standard default list of 

SYS1 .PARMLIB members to be used. 

NIP references the modified list to get 
the name of the system parameters 
member. NIP processes this member 
and then continues with the other 
parameters entered by the operator. 

NIP passes the modified list to MSI and 
gives control to MSI, which processes all 
other members indicated on the 
modified list. 

Initialization is complete. 


The keyword identifies either a member of 
SYSI.PARMLIBoracard reader. The mem- 
ber or card deck so identified lists the mem- 
bers of SYS1 .PARMLIB that hold the 
initialization parameters to be used. 

The operator is advised if any abnormal 
conditions or invalid parameters are 
detected. 

The operator is advised if any abnormal 
conditions or invalid parameters are 
detected. 
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Implementation of Automatic Commands 



Although system generation options used in os/vsl Release 1 have not been 
changed for automatic commands, a new implementation is now used. Any auto- 
matic commands must be put in an automatic commands member of sysI.parmlib 
and automated system initialization must be invoked. The automatic start com- 
mands formerly generated via the starti, startr, and startw parameters of the 
SCHEDULR system generation macro must be placed in an automatic commands 
member. A system generation deck containing these parameters can be used to 
generate the new-release system, but the parameters are ignored. 



Creating SYS1 .PARMLIB Members 



Naming Conventions for 
SYSI.PARMLIB Members 



You can use the iebupdte utility program to place parameter lists in members of 
the system parameter library, sysI.parmlib. (This utility is also used to main- 
tain the members of sysI.parmlib.) The parameter lists are composed of 80- 
byte records, formatted much like the entries that the operator would be re- 
quired to make in a manual initialization. The format, contents, and processing 
of these parameter lists are described in the following paragraphs. 



The names used for the sysI.parmlib members that hold parameters for use in 
automated system initialization signify the types of parameters they hold. Each 
name consists of from three to eight characters, the first three of which signify 
the member's contents: 



First Three 
Characters 

NIP 

JES 

DFN 

SET 

PRE 

CMD 

SMF 

RES 



Contents of the Member 

System Parameters 

JES Reconfiguration Parameters 

DEFINE Parameters 

SET Parameters 

Permanently Resident Volume List Parameters 

Automatic Commands 

SMF Parameters 

RTAM Parameters 



The name used for a member of sysI.parmlib that lists the other members to be 
used in an initialization is not bound by this "first three characters" convention. 



Formats of SYSI.PARMLIB 
Automated Initialization 
Members 



In general, the formats of the automated system initialization members are the 
same as the formats that the operator would use if he were entering the param- 
eters on the system console. The format of each type of automated initialization 
member is described in the following paragraphs. 



Member (or Card Deck) 
that Lists Members 
to be Used 



The following format restrictions apply to the listing member referenced by the 
AUTO keyword and the card deck referenced by the rdr keyword. This member 
(or card deck) consists of a list of member names to be used to alter the de- 
fault list of member names in nip. 
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The System Parameters 
(N/Pxxxxx) Member 



The DEFINE Parameters 
(DFNxxxxx) Member 



• Each record (or card) holds only one member name. 

• A member name may start anywhere in the record (or card) as long as it is 
completed by column 71. 

• A member name must be delimited by a blank. 

• Comments may be placed after the delimiter. 

• A record ( or card ) having its first 71 columns blank is ignored. 

• The member names must be consistent with the naming conventions pre- 
viously described. (The naming conventions permit you to list the member 
names in any order. ) 

• Adding "null" to the three required characters to form a member name (for 
example, smfnull) causes the corresponding entry in the default list to be 
m.ade null ( blanks ) . 

This member consists of entries made in the same format as if they were entered 
by an operator at the console. The following format restrictions apply to this 
type of member: 

• The AUTO and rdr keywords are invalid entries. 

• An entry may start anywhere in the record as long as it is completed by 
column 71. 

• Continuation onto several cards is signalled by either 

the CONT keyword, or 

a comma followed by a blank. 

This member consists of the parameters of the define command in the same 
format as if they were entered by an operator at a console. The following for- 
mat restrictions apply to this member: 

• An entry may start anywhere in the record, but it must be completed by 






The Automatic Commands 
(CMDxxxxx) Member 



• All records are read and processed in the order they are read in as long as they 
are syntactically correct. 

To determine which parameters you want to place in the member, see the 
parameter descriptions in the response to message iee802a in OS/VS Message 
Library: VSl System Messages. 

This member consists of any system commands you want executed during sys- 
tem initialization; for example, start commands, logon commands, and vary 
commands. The commands must be in the same format as if they were entered 
by an operator at the console. All commands contained in this member are dis- 
played on the console unless nolist was specified in the auto or rdr keywords. 
The following format restrictions apply to this member: 

• Only one command per record is allowed. No continuation is permitted. 

• An entry may start anywhere in the record, but it must be completed by 
column 71. 
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The Permanently Resident 
Volume List Parameters 
(PRExxxxx) Member 



For a description of this member, see the presres description in the section The 
PRESRES Volume Characteristics List. 



The SMF Parameters 
{SMFxxxxx) Member 



The SMFxxxxx member controls smf operations. This member consists of a series 
of parameters contained in 80-character card-image records. To determine which 
parameters you want to place in the member, see the description of smfdeflt 
parameters in OS/VS System Management Facilities ( SMF ) , GC35-0004. 



The JES Reconfiguration 
Parameters (JESxxxxx) 
Member 



For a description of this member, see the jesparms description in the section 
JES Reconfigurability. 

Unless it is necessary to override the values specified at sysgen, do not specify 
JESXXXXX (that is, let the null entry be generated). This allows the system to 
bypass all the i/o related to overriding the sys gen-specified values. 



The SET Parameters 
(SETxxxxx) Member 



The RTAM Parameters 
[RESxxxxx) Member 



This member consists of the parameters of the set command in the same format 
as if they were entered by an operator at a console, with these exceptions : 



• The unit address (unitaddr) in the q= and proc: 
with a volume identification ( volid ) . 



keywords has been replaced 



• A new keyword, qparm^t ( jobqueue parameters), has been added. For a de- 
scription of the jobqueue parameters, see message ief423a in OS/VS Message 
Library: VSl System Messages, GC38-1001. 

• The date, clock, and gmt operands cannot be used in this member. If date 
and CLOCK are specified, they must be in reply to message ieaIOIa or in a set 
command issued after initialization. If gmt is specified, it must be in reply to 
message ieaIOIa. 

For a description of this member, see the discussion of the sysI.parmlib mem- 
ber in the RES System Programmers Guide. 



Performing Automated System Initialization 



During initialization, nip generates the message 

IEAIOIA SPECIFY SYSTEM AND/OR SET PARAMETERS FOR RELEASE xx.yy.sssss 
ivhere: 

XX is the release number 
yy is the release level 
sssss is the system type 

The operator's response to this message consists of a selection of keyword param- 
eters. The formats and pmposes of all parameters are described in OS/VS 
Message Library: OS/VSl System Messages, GC38-1001. 
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Because of automated system initialization, the following parameters are in- 
cluded in the list of eligible keywords. Their purposes are briefly as follows: 

Keyword Purpose 

AUTO To specify a SYSl.PARMLIB member that lists other members to be used in 

automated system initialization. The NOLIST option of this keyword prevents 
the sending to any consoles non-critical informational messages issued bv NIP or 
MSI. 

RDR To specify a readied card reader holding a deck of cards that lists members of 

SYSl.PARMLIB to be used in automated system initialization. The NOLIST 
option of this keyword prevents sending non-critical informational messages, issued 
by NIP or MSI, to any consoles. 

DATE To set the date in the TOD ( time-of-day ) clock. 

CLOCK To set the time of day in the TOD clock. 

GMT To express the time of day in Greenwich Mean Time. 

Q To specify the DASD that holds the system job queue ( SYSl.SYSJOBQE ). 

PROC To specify the DASD that holds the system procedure Hbrary (SYSl.PROCLIB). 

SPOOL To override spool parameters. 

DEVSTAT To specify device type(s) for NIP device status checking. Devices of the type(s) 
indicated are tested for a not-ready condition. The UCB for any checked device 
in a not-ready condition is marked as offline. Otherwise, each UCB is left marked 
as online. 

Automated system initialization results if either auto or rdr is specified in the 
reply to message ieaIOIa. A normal (manual) initialization results otherwise. 

In an automated initialization, the set parameters date, clock, and gmt 
should be specified in the reply to message ieaIOIa only if they must be changed. 
The other set parameters (q, proc, and spool) should be specified in the reply 
to message ieaIOIa if a set parameters member is not used or if like parameters 
in the set parameters member to be used must be overridden. Another oppor- 
tunity for specifying set parameters is not given unless an error occurs. 

If NIP detects a parameter in the wrong format or an invalid parameter, nip 
issues a message indicating the error. The operator must then respecify the 
parameter and any system or set parameter that nip has not yet processed, (nip 
processes the parameters in the same sequence as they were entered by the 
operator and does not process any parameters after an error is encountered.) 

In a manual initialization, the operator may specify the set parameters Q, 
proc, and spool in either the reply to message ieaIOIa or the reply to message 
iee114a, which occurs after nip has completed its processing. If they are specified 
in the reply to message ieaIOIa, message iee114a is not generated. 

nip processes each keyword in the reply to message ieaIOIa in the same 
sequence that the operator specifies them. Therefore, to override any keyword(s) 
specified in the system parameters member for a particular initialization, the key- 
word(s) must be specified after the auto or rdr keyword in the reply to message 
ieaIOIa. 

The NOLIST subparameter of auto and rdr takes effect after the time is entered, 
so it cannot affect any entries made prior to the auto or rdr keyword entry. 
NOLIST prevents the generation of the ieeIOIa ready message and other non- 
critical messages. 
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Any SET parameters (q, proc, and spool) passed from nip to msi override the 
corresponding keywords specified in the set parameters member. 

Note: The term "SET parameters" is used differently here than in other systems where such 
parameters were specified by an operator's use of the SET command. In VSl, the SET com- 
mand is not related to Q, PROC, and SPOOL parameters. 



Processing Notes 

The List of SYSl.PARMLIB 
Members to be Used 



The list of sysLpabmlib member names referenced by the auto or rdr keyword 
contains the names of the members in the following table. If neither auto nor 
RDR is specified by the operator, the default list shown in the following table is 
used during initiaHzation. 



Members 


Default 
List 


System Parameters 

JES Reconfiguration Parameters 

DEFINE Parameters 

SET Parameters 

Permanently Resident Volume List Parameters 

Automatic Commands 

SMF Parameters 

RTAM Parameters (if RES is included at SYSGEN) 


Null Entry* 
JESPARMS 
Null Entry* 
Null Entry* 
PRESRES 
Null Entry* 
SMFDEFLT 
RESPARMS 


*A Null Entry consists of all blanks 





Use of the default list results in the manual initialization procedure, with the 
exception that the set parameters can be specified in the reply to message 
ieaIOIa along with system parameters, or in the reply to message iee114a, but 
not at both times. Processing of the list ends when: 

• An end-of-file condition occurs on the card reader or 

• The number of entries processed equals the number of entries in the default 
list. 



If the list provided contains fewer member names than the default list, the re- 
maining names are taken from the default list. The default list is thus altered by 
the names provided in the member. Once the default list has been altered, nip 
processes its member (the system parameter member) for system parameters 
before continuing to process the operator's other replies to the message ieaIOIa. 

If the system parameters member is null, no member is processed. Any change 
to the sysgen specifications must have been entered in response to the ieaIOIa 
message. 

If a syntax error occurs, processing up to that point will have been completed, 
and the default list will have been altered up to that point. The record contain- 
ing the syntax error is written to the console and control is returned to the 
operator. 
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The System Parameters 
(NIPxxxxx) Member 



Processing of this member is the same as if the parameters had been entered by 
the operator at the console. An error in this member not only terminates the 
processing of this member, but also terminates processing of any keywords that 
followed the auto or rdr keyword entered by the operator. 



The Define Parameters 
(DFNxxxxx) Member 



Processing of this member is the same as if the parameters had been entered by 
the operator at the console. Error detection and recovery are also the same as if 
the entry was a reply by the operator. 



The SET Parameters 
(SETxxxxx) Member 



Processing of this member is the same as if the parameters had been entered by 
the operator at the console. 



The Automatic Commands 
(CMDxxxxx) Member 



the operator at the console. All commands are displayed on the console unless 
NOLiST was specified in the auto or rdr keyword. 
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OS/MFT-OS/VSl Differences 



This section contains a resume of some of the more 
significant differences between os/mft and os/vsl. It 
is intended as a quick reference aid for the system 
programmer involved in a conversion from mft to 
vsl. The differences appear in random order, and the 
sequence of their presentation in no way implies a 
level of importance or significance. Differences listed 
include enhancements, restrictions, and changes 
necessitated by the implementation of a virtual storage 
system. 



OS/MFT - OS/VSl Differences DIF 1 
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OS/MFT-OS/VSl Differences 



1. jES readers and writers do not require a partition, but a partition must be 
available to start and stop them. Additionally: 

• The start reader and start writer commands do not require partition iden- 
tifiers. 

• A "hot reader" capability is provided for unit record readers. ( Unit record 
readers remain ready to process input, after being started, until they are 
stopped. It is not necessary to issue a reader start command after reloading 
the reader following an empty hopper condition.) 

• A WRITER command enhancement is provided to control writer output ac- 
tivity, such as the number of copies, forward space functions, and backspace 
functions. 

• The sequence of the writer output has been changed. The output now 
follows the sequence: 

^ I Messages and jcl are interspersed for multi-step jobs. 

Program output 

2. The number of job classes that may be specified per partition has been in- 
creased from 3 to 15. 

3. The interpreter function is no longer a subtask of the reader. Instead, the 
function occurs at job initiation time, as a subroutine to the initiator. 

4. The contents of the job queue has been changed in vsl. A swads data set is 
now provided for each initiator, and this reduces the contention that exists 
for the job queue in mft. 

5. With the implementation of jes, a spool data set is provided. In addition to 
SYSiN and sysout, jcl, messages, wtp messages, and system log data sets are 
included in the spool data set. 

6. Programs compiled using pl/i f and using the teleprocessing facilities of this 
language translator cannot be run under vsl because pl/i f uses qtam as its 
teleprocessing access method. These programs can be recompiled using the 
pl/i checkout compiler or the pl/i optimizing compiler, both of which use 
tcam as their teleprocessing access method. 

7. Programs which previously required storage approaching 64K, 128K, 192K, 
etc. may require an additional 64K of virtual partition area to accommodate 
the system requirements (such as pqa area) of vsl. 

8. mft supports tape and disk for smf output, vsl supports disk only for smf 
output. 

9. Programs that modify active ccw strings require changes in order to execute 

in a virtual storage system. 

10. Commands in the input stream between jobs are processed at reader time; 
those within the job, at interpreter time. 
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11. Users with i/o appendages must code a page-fix appendage in their pro- 
grams to interface with los and fix the i/o appendages associated with the 
program. 

12. Changes are required in all programs that declare or reference certain psw 
fields directly, such as the system mask, interrupt code, condition code, 
program mask, ilc, and bit 12 of the psw. 

13. Programs using the ssk and isk instructions will be affected because the 
operand 1 register now contains the "change and reference" bits as well as 
the storage key and fetch protect bit. 

14. The ssM instruction will have degraded performance due to interrupt pro- 
cessing. 

15. Programs that execute the lpsw instruction must be carefully checked be- 
cause of the changes in the psw format. 

16. No Excp support is provided for sysin/sysout data sets. 

17. DSCBs and user labels are not supported with sysin/sysout data sets. 

18. SMF data set compatibility is not supported because the format and content 
of SMF records has changed under vsl. 

19. vsl does not support: 

Main storage hierarchies ( obviated by virtual storage concept ) 

QTAM (superseded by TCAiM) 

RJE (superseded by RES ) 

lEBUPDAT (superseded by lEBUPDTE) 

TESTRAN ( low usage component of MET ) 

GJP ( low usage component of MET ) 

SGJP ( low usage component of MET ) 

IBCRCVRP (superseded by lEHATLAS) 

HASP 

IMAPTELE (replaced by HMAPTELE) 

IMDMDMAP (replaced by HMBLIST) 

IHGUAP Utility (low usage component of MET) 

20. vsl does not support these devices: 
IBM 1017 

1018 

1285 

2301 

2303 

2305-1 

2311 

2321 

2841 

7772 

21. MET provides three reader procedures with the system, vsl provides two, 
RDR and RDRT. rdr400 and rdr32(X) are not included in vsl. vsl also includes 
two writer procedures, wtr and wtrt. 

22. Partitions in vsl have a minimum size of 64K and must be multiples of 64K 
in size. 

23. The resident svc, ram, and bldl default lists have been changed in vsl. 

24. Resident options may be made non-pageable or pageable in vsl. 
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25. AH problem program output is spooled to dasd by jes under vsl and unit 
record ucbs are not created. Any user programs that handle conditions 

such as print overflow (channel 12) by checking bits in the ucb will not 
operate properly. 

26. vsl TCAM line groups can contain a maximum of 32 lines, except for the ibm 
2260 (local attachment), for which there is no maximum. 

27. RBs, etc. are not part of the problem program area in vsl. They have been 
moved to the pqa. 

28. A PQA (one per partition) is provided in vsl. This does not exist in os/mft. 

29. Programs that reference storage not obtained with getmain or referenced 
after a freemain may not execute. 

30. In MFT systems, sysin blocking factors are selected prior to job initiation, and 
RSAM users have to either write code accommodating the block size selected 
or explicidy provide jcl overrides. In vsl, the blocking done by the system 
is transparent to the user. For the bsam interface, records are dynamically re- 
blocked to user requirements during execution. 

31. No DADSM facilities (obtain, scratch, rename) are supported for the sysin/ 
SYSOUT data set in vsl. 

32. SYSOUT data sets can only be written sequentially without repositioning. No 
Support is provided for note/point, for update, or for reading sysout. Once 
written, sysout records cannot be erased or overlaid. 

33. In vsl, note/point support for sysin is restricted as follows: 

a. The user must save four bytes of data (ttrl) instead of three as in mft. 

b. POINT to following record ( ttrOI ) is not supported. 

c. Track numbers (n) do not begin with and are not in ascending sequence. 

34. No SYSIN support is provided for update or for overlaying or adding to the 
data. 

35. SYSiN support for variable length records is not compatible. For mft, block 
and record descriptor fields must be punched (in binary) in the input card 
image. In vsl, the entire 80-byte image is treated as data, and block and 
record descriptor fields are prefixed to it. Both blocked and unblocked formats 
are supported for sysin, but spanned records are not. (vs and vbs are sup- 
ported for SYSOUT along with the other variable length formats. ) 

36. All SYSiN records processed by qsam contain one logical record per original 
80-byte card image. It is not possible to divide cards into multiple logical 
records or combine multiple cards into a single logical record except by 
using BSAM with user deblocking routines. 

37. BSAM svcs BSP and feov are not supported in vsl and will result in an error 
return if issued. 

38. synadf may only be issued from within a synad exit in vsl. 
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39. SAM chained scheduling is supported for v=:r jobs only. If a user is not running 
v=:R and specifies chained scheduling, regular scheduling will be substituted. 

40. TCAM message control programs and tcam message processing programs 
using the icopy, tcopy, qcopy, and tchng macro instructions must be re- 
assembled and linkage edited, tcam message processing programs not using 
any of these macro instructions only need to be re-linkage edited. 

41. Additional jcl parameters are provided in the job and exec statements to 
facilitate running v=r jobs. 

42. MFT reader procedures will not run in vsl after release 1. Because the farm 
field of the exec statement is changed, user reader procedures must be up- 
dated. 

43. MFT stand-alone dasdi will not run in vsl after release 1 because the ipl text 
has been changed. 

44. In MFT (and in release 1 of vsl), reentrant user programs could modify 
themselves (for example, store registers into the user area). Such attempts 
will now cause a protection check. 
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VS1 Features and Options 



This section contains a brief description of some of 
the features and options available in vsl. Although 
comprehensive coverage of all the features and op- 
tions available is not provided, this section will serve 
as an aid to the planner responsible for determining 
if a specific optional feature or option should be in- 
cluded in (or excluded from) the system at system 
generation time. Features and options are arranged in 
the section in alphabetic sequence. 



Section Outline 



VSl Features and Options FEA 1 

Alternate Path Retry (APR) FEA 3 

Attach Function FEA 3 

Attach Function Made Resident FEA 3 

I Automatic Partition Redefinition FEA 4 

Automatic Volume Recognition (AVR) FEA 4 

Basic Direct Access Method ( BDAM ) FEA 4 

Basic Indexed Sequential Access Method ( BISAM ) . . FEA 5 

Basic Partitioned Access Method ( BPAM ) FEA 5 

Basic Sequential Access Method ( BSAM ) FEA 5 

BLDL Table Made Non-Pageable FEA 6 

Channel Check Handler (CCH) FEA 6 

Checkpoint Restart Facility FEA 6 

Consoles — Alternate and Composite Consoles 

Options FEA 7 

Consoles — Multiple Consoles Support ( MCS ) FEA 7 

Conversational Remote Job Entry ( CRJE ) Facility . . FEA 9 

I DEB Validity Checking FEA 9 

uevice Independent Display Operator Console 

Support ( DIDOCS ) FEA 10 

Direct Access Volume Serial Number Verification . . . FEA 10 

Dynamic Device Reconfiguration (DDR) FEA 10 

I Dynamic Dispatching FEA 11 

Dynamic Support Systems ( DSS ) FEA 12 

Extract Function Made Resident FEA 13 

I Fetch Protect FEA 13 

Graphic Programming Services ( GSP, GAM ) FEA 14 

I Greenwich Mean Time FEA 14 

Identity Function Made Resident FEA 15 

Indexed Sequential Access Method (ISAM) FEA 15 

I I/O Load Balancing FEA 15 

Job Step Timing FEA 16 

Machine Check Handler ( MCH ) FEA 16 

I Missing Interruption Checker FEA 16 

Multiple Wait Option FEA 17 

On-Line Test Executive Program (OLTEP) FEA 17 

Program Controlled Interrupt (PCI) FEA 18 

Queued Indexed Sequential Access Method ( QISAM ) FEA 19 

Queued Sequential Access Method ( QSAM ) FEA 19 



Continued — 
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Reenterable Load Modules Made Resident FEA 19 

Resident Access Method Routines FEA 19 

Shared DASD FEA 20 

SPIE Routines Made Resident FEA 20 

Storage Protection Option FEA 20 

System Management Facilities ( SMF ) FEA 20 

Telecommunications Option FEA 21 

Time-Slicing Facility FEA 23 

Trace Option FEA 24 

Transient SVC Table . , : FEA 24 

Types 3 and 4 SVC Routines Made Resident FEA 25 

User Modify Logical Cylinder Facility FEA 25 

User-Added SVC Routines FEA 26 

Validity Check Option FEA 27 

Virtual Storage Access Method (VSAM) FEA 27 

Volume Statistics Facility FEA 28 
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Alternate Path Retry (APR) 



Arracn runcrfon 



Status: Optional. (The function is standard with the system but is effective 
only when the optchan= operand of the iodevice macro is coded. ) 

The alternate path retry (apr) option allows an i/o operation that has de- 
veloped an error on one channel path to a device to be retried on another 
channel path to the same device. This can be done only if another channel path 
has been assigned to the device performing the i/o operation, apr also provides 
the capability to vary a path to a device online or offline by use of the vary 
command. 

APR can handle: 

• Up to four paths to one device. 

• The ninth drive on a 2314. 

While it is not module-dependent, apr performs its function usefully only in 
a system that has the channel check handler (cch) and alternate paths to at 
least some of the i/o devices, cch checks for channel errors, analyzes the error, 
and produces an interface that aids in setting up an alternate path retry. 

The operation of the selective retry function of apr, in conjunction with the i/o 
supervisor, does not depend on anything you do. The operator can initiate the 
VARY path function by entering the vary path command in the input stream or 
at the console. 



Status: Standard. 

The ATTACH function, with subtasking, creates subtasks so that the issuing 
program and the program requested in the attach macro instruction compete 
for system resources. The function allows more than one task to be operative 
within a partition. 



Attach Fuiiction Made Resident 

Status: Standard. 



The routines that make up the attach function are resident in storage in vsl. 
This function is optionally resident in os met. Having the routines resident 
eliminates the necessity of bringing them into the supervisor transient area each 
time an attach macro instruction is issued. 
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Automatic Partition Redefinition 

Status: Standard. 



The addition of the keyword PARM=membemame to the define command 
allows the operator to redefine partitions more easily. Using this keyword, the 
operator can specify a sysI.parmlib member containing partition redefinitions. 
This causes the system to go to that member to obtain the redefinitions. The 
operator is thus relieved from entering the redefinitions from the console. 

The member consists of entries in the same format as if they were entered from 
the console. If end is not in the parameters, the redefinition can continue through 
operator replies. No restriction is made on where entries must start, but the last 
entry must be completed by column 71. Blank records are ignored. The param- 
eters contained in the member are the same as those given in response to 
message iee802a (see OS/VS Message Library: VSl System Messages, GC38- 
1001). 



Automatic Volume Recognition (AVR) 



Staus: Optional. Included when vlmount=avr is specified in the schedulr 
macro instruction. 

This feature issues volume mounting instructions to the operator to minimize 
the time lost in performing job setups. The operator can premount labeled 
volumes on any available tape or disk device. The identification of the volume 
and the device used is automatically recorded in a table. 

When a particular volume is needed for job setup, the table containing the 
volume information is searched. If the required volume is already mounted, the 
usual procedure of issuing a volume mounting message is bypassed. This 
feature is advantageous in installations where work schedules are normally set 
in advance and follow a repeated pattern. 



Basic Direct Access Method (BDAM) 

Status: Standard. 



In the Basic Direct Access Method (bdam), records within a data set are 
organized on direct access volumes in any manner chosen by the programmer. 
Storage and retrieval of a record is by actual or relative address within the data 
set. This address can be that of the desired record or a starting point within 
the data set where a search for the record, based on a key furnished by the 
programmer, begins. Addresses are also used by bdam as a starting point for 
searching for available space for new records. 
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Basic Indexed Sequential Access Method (BISAM) 



Status: Optional. Included when acsmeth^isam is specified in the datamgt 
macro instruction. 

Sequential and direct processing are provided by the Indexed Sequential Ac- 
cess Methods (isam). Records are maintained in control field sequence by key. 
The system maintains a multilevel index structure that allows retrieval o£ any 
record by its key. Additions can be made to an existing isam data set widiout 
rewriting the data set. 

The Basic Indexed Sequential Access Method (bisam) stores and retrieves 
records randomly from an indexed sequential data set. Selective reading is 
performed using the read macro instruction, specifying the key of the logical 
record to be retrieved. Individual records can be replaced or new records can 
be added randomly. 



Basic Partitioned Access Method (BPAM) 

Status: Standard. 



The Basic Partitioned Access Method (bpam) is designed for efficient storage 
and retrieval of discrete sequences of data (members) belonging to the same 
data set on a direct access device. Each member of the data set has a simple 
name. The data set includes a directory that relates the member name with the 
address where the sequence begins. Members may be added to a partitioned data 
set as lonP' as snane is available in the dirf^cforv and the data set 



Basic Sequential Access Method (BSAM) 

Status: Standard. 



In the Basic Sequential Access Method (bsam), data is sequentially organi- 
zed and physical blocks of data are stored or retrieved. The read/write macro 
instruction causes the initiation if an input/output operation. The completion 
of these operations is tested by using synchronization macro instructions. Auto- 
matic translation between ebcdic and ascii codes is provided for magnetic tape 
labels and record formats. 
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BLDL Table Made Non-Pageable 



Status: Optional. Invoked by the specification of options=bldl in the 
CTRLPROG macro instruction. 

The BLDL table is always resident in vsl. However, the user has options as to 
the entries he wishes to include in the table and as to whether he wants the 
table to be pageable or non-pageable. Having the table non-pageable eHminates 
the necessity of paging the table into real storage whenever the function is re- 
quired. See the Resident Routines Options section of this publication for a com- 
prehensive discussion of the function. 



Channel Check Handler (CCH) 

Status: Standard. 



The Channel Check Handler ((Xh) intercepts channel-check conditions, per- 
forms an analysis of the environment, and facilitates recovery from channel- 
check conditions by allowing for the scheduling of device-dependent error re- 
covery procedures by the input/output supervisor, which will determine whether 
the failing channel operation can be retried. 



Checkpoint Restart Facility 



Status: Optional. The facility is standard in the system, but the user must 
code the REsroNT=(ACSMETH) parameter in the ctrlprog macro instruction 
to use it. You can also indicate the abend codes that you want to be eligible 
or ineligible for automatic restart, in the notelig and eligble parameters 
of the CKPTREST macro instruction. 

The checkpoint/restart facility expands the use of the restart capabilities that 
are provided by the bd parameter of the job and exec statements. The kd para- 
meter permits execution of jobs to be restarted automatically at a job step after 
abnormal termination occurs. 

Checkpoint/restart enables you to write checkpoint macro instructions (chkpt) 
at various points in your program to record job status information. Then when 
an ABEND occurs, your program can be restarted automatically at the last of these 
points, or restart can be deferred until a later time, when the job can be resub- 
mitted and the restart parameter in the job statement used. The ed parameter 
can also be used to suppress partially or totally the checkpoint/restart facility. 

The following restrictions apply to the establishment of a checkpoint by the 
CHKPT macro instruction. 



• 



When the checkpoint is established, the job step must comprise a single task. 
The job step task must be the only task when the job step is restarted. 
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• A checkpoint cannot be established by an exit routine that returns control 
to the control program. 

• If a STiMER or WTOR macro instruction has been issued, a checkpoint cannot 
be established before the time interval is completed or the operator's reply is 
received. 

Under certain conditions, such as the following, a checkpointed job may not be 
restarted at will: 

• If a job took a checkpoint while running v=r, that job cannot be restarted 
while another partition is using part or all of the required v=:r space. The job 
to be restarted must wait until the v^r space is available before restart is 
possible. 

• If a job took a checkpoint while running v=r, and the system queue area 
(sqa) has expanded into the v=r space required to restart the job, restart is 
not possible until the system is re-iPLed and the v=r address space is again 
made available. 



Consoles — Alternate and Composite Console Options 



Status: Optional. Alternate consoles are optionally specified in the altcons^ 
parameter of the schedulr macro instruction. 

One primary console must always be specified for any vsl operating system. 
One alternate console can be specified. A composite console, such as a card 
reader and a printer, can be specified as a primary or an alternate console. The 
composite console is considered one console even though it may consist of 
two different physical devices. 

The following guidelines apply when Multiple Console Support (mcs) is not 
selected: 

• A primary console must be specified in the schedulr macro instruction. 

• A composite console can be used as a primary or an alternate console. 

• When a graphic device is going to be active as a console, a device that pro- 
duces printed output must be specified. 



Consoles — Multiple Consoles Support (MCS) 



Status: Optional. Included by specification of the options^mcs parameter 
of the SCHEDULR macro instruction. 

You must specify the multiple console support (mcs) option to have two or 
more consoles active during execution. One console must be specified in the 
schedulr macro instruction; it is called the "master" console. An alternate con- 
sole for the master console must be specified in the altcons parameter of the 
SCHEDULR macro instruction. A seconsle macro instruction must be coded defining 
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the alternate as a secondary console. Additional secondary consoles can be defined 
with SECONSLE macro instructions— up to a maximum of 31 secondary consoles. 
For all consoles for which no alternate console is specified, the master console 
is automatically assigned as the alternate. 

A hard copy log can be specified either at system generation or by the operator 
during system initialization or execution. A hard copy log is required when there 
is more than one active console during initialization or execution, or when there 
is an active graphic console. The hard copy log can be the system log that is 
contained on sysI.sysvlogx andsYsl.SYsvLOGY, or it can be a console with output 
capability. If the log is required, the system records the operator commands, 
the system commands and responses, and the messages with routing codes of 1, 
2, 3, 4, 7, 8, and 10 on the hard copy log. Additional messages can be recorded 
if desired. 

Routing codes and descriptor codes are required for all messages handled by 
a system using mcs. Messages that already exist can be assigned routing codes 
at system generation time or, by default, they will be sent to the master console. 

Routing codes are assigned to all new operator messages (wto and wtor). 
They designate what function the message is connected with and determine 
where a message will be sent. A system generation parameter provides the 
ability to supply routing codes to all operator messages that already exist and 
do not have routing codes. 

Each console is assigned one or more routing codes. The routing codes as- 
signed to a console are matched to the routing codes assigned to wto and wtor 
messages. If there is a match, the message is sent to the console. Some messages, 
such as a message that is broadcast to all active consoles, are not routed by the 
routing code. 

Descriptor codes must be specified for all new operator messages. They are 
specified in the wto or wtor macro instructions. They designate how a message 
is to be printed or displayed. 

All commands have been arranged by function into four command code 
groups: informational, system control, i/o control, and console control. 

An exit, just before the routing codes of a message are checked, to enable 
you to supply your own routine to add, delete, or change routing and descriptor 
codes is provided. ( See the Message Routing Exit Routines section of this publi- 
cation for a description of the exit routine.) 

The following guidelines must be used: 

• If HAKDCPY=sYSLOG is specified in the schedulr macro instruction during 
system generation, then at ipl time the operator must change the hardcpy 
parameter to refer to the address of an operator console that has output 
capability. The device should not be the master console. The hardcpy speci- 
fication can be changed back after the message iee141i has been received. 

• Master console must be specified in the console keyword parameter of the 
schedulr macro instruction. 

• An alternate console to the master console must be specified in the altcons 
keyword parameter of the schedulr macro instruction. 

• The alternate for the master console must be defined in the console parameter 
of a SECONSLE macro instruction to make it a secondary console. 

A console with at least printing output capability must be specified as the 
hard copy log. Although the system log is not a console, and does not directly 
produce printed output, it can be used. 



• 
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• A record of the operator commands, system commands and responses, and 
routing codes 1, 2, 3, 4, 7, 8, and 10 should be maintained. 

• Up to 31 secondary consoles can be specified with seconsle macro instructions. 
They can all have alternate consoles specified. If no alternate is defined, then 
the master console automatically becomes the alternate. 

• A 2250 display unit can be specified as a master, secondary, or alternate 
console. 

• Any number of the consoles can be composite consoles. 

• Routing and descriptor codes are assigned to all new operator messages that 
are written. 



Conversational Remote Job Entry (CRJE) Facility 



DEB Validity Checking 



Status: Optional. Included by specification of the options=crje parameter 
in the schedule macro instruction. 

The conversational remote job entry (crje) facility provides remote access 
to the operating system from printer-keyboard terminals. Authorized terminal 
users can conversationally prepare and update programs and data, submit them 
for OS background processing, and receive the output either at the central in- 
stallation or at the remote terminal. 

crje is specified at system generation time in order to have the necessary 
modules included in the system. After generation, you must create the specific 
CRJE system required for your installation. There are three macro instructions 
available for this job— crjeline, crjetabl, and crjeuser. You set up a job that 
mcj.U\j.es Lj-iQ CRjE macro msLructions necessary lO speciiy your systcmj you may 
include your own routines. The assembler translates these macro instructions 
and creates the required modules. The linkage editor incorporates the modules 
into the operating system. 

SYsl.MACLiB must be in the operating system so that the assembler can expand 
the macro instructions. sysI.telcmlib must be in the system to hold some of 
the crje load modules as well as the telecommunication subroutines. Enough 
system queue space must be specified in the ctrlprog macro instruction during 
s'^stem o"eneration to handle the necessar*'' grte s^^ace requirements. 



Status: Standard. Reduced deb validity checking is obtained by specifying 

OPTiONS=NODEBCHK in the CTRLPROC macro instruction. 

deb validity checking is designed to prevent a user's data set (associated with 
a given deb) from being read or modified, either accidentally or intentionally, 
by another user program. In full deb validity checking, system open routines 
provide protected deb entry creation and validation, los provides additional ( and 
important) validation each time i/o is performed, and system close routines 
provide deb entry validation and deletion. 

Although some degree of data set security is achieved by the open and close 
functions, it is substantially reduced without the los portion of deb validity check- 
ing. Specification of options =nodebchk removes los linkage to the deb validity 
check module, thus limiting the overall effectiveness. In installations where data 
set security is a primary concern, full deb vaHdity checking should be allowed 
(that is, options=:nodebchk should not be specified). 
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Device Independent Display Operator Console Support (DIDOCS) 

Status: Optional. 



The device independent display operator console support (didocs) provides 
uniform operator console support for a range of display devices, didocs is in- 
cluded in your system when a display console and multiple console support 
(mcs) are specified. 

DIDOCS provides the capability to: 

• Print out messages from the vsl control program and problem programs to 
the display console device. 

• Enter commands from the display console to the control program by the 
alphanumeric keyboard and/or the light pen, when available. 

• Print two out-of-line status displays as requested by the status display support. 

Status display support provides for the presentation of information to a system 
operator clearly and understandably. It also provides the ability for messages 
to a display device to be displayed out of line in a special area of the screen. 
This allows related messages to be grouped together and easily read by the 
operator. 



Direct Access Volume Serial Number Verification 



Status: Optionally Excludable. The facility will be included in the system 
unless oPTiONS=NODAV is specified in the ctrlprog macro instruction. 

The direct access volume serial number verification facility checks or verifies 
the volume serial number of a volume after an unsolicited device-end interrupt 
condition has been corrected and the volume has been put back online. 

When an unsolicited device-end interrupt is received from a direct access 
device, the i/o supervisor ensures that the volume serial number of the mounted 
volume agrees with the volume serial in the unit control block (ucb). 



Dynamic Device Reconfiguration (DDR) 



Status: Optionally Excludable. The facility will be included in the system 
unless OPTiONS^NODDR or noddrsys is specified in the ctrlprog macro in- 
struction. 

The dynamic device reconfiguration option allows a demountable volume to 
be moved from one device to another and repositioned if necessary without 
abnormally terminating the job or redoing epl. A request to move a volume may 
be initiated by either the system or the operator. 

The system transfers control to the ddr routines when a permanent i/o error 
occurs. These routines then determine whether another device of the same type 
to which the volume can be moved is available. When another device is avail- 
able, the system requests a volume swap by issuing a message to the operator. 
The operator must answer this message by entering a swap command. 
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Dynamic Dispatching 



Notes: 

• You should not code specific unit addresses in programs that will be processed on a 
system that has DDR. 

• The direct access serial number verification routines must be in the system that has 
the DDR routines. 

For FETCH: When i/o errors occur while the fetch routines are addressing 
the svcLiB, the ddr system residence routines receive control, and, if possible, 
request a swap. For this to occur, options=ddrsys must be specified in the 
CTRLPROG macro instruction and the conditions listed above must exist. 
For DDR System Residence Routines: When these routines are specified in the 
OPTIONS keyword parameter of the ctrlprog macro instruction, another keyword 
parameter, altsys, must also be specified. 

If high availability is important to the installation, a duplicate system residence 
volume is advisable. However, to use such a volume, writing on any part of the 
system residence volume other than sysI.logrec would have to be prohibited. 

The alternate residence device specified during system generation can be 
changed at ipl time by the operator. 

For Nonstandard Labels: If you want ddr and have nonstandard magnetic 
tape labels, options=ddrnsl must be specified. A nonstandard label routine 
with the name nsoiepos must be supplied. This routine can either be added 
during system generation using the svclib macro instruction, or be link-edited 
into svCLEB after the system generation process is completed. 
For DR when EXCP is Used: When the excp macro instruction is used to ad- 
dress magnetic tape drives in a program that will run under a system with 
DDR, REPOs==Y or N must be coded in the dcb macro instruction to indicate 
whether an accurate block count is being maintained. 



Status: Optional. Included in the system by specification of the dynpart= 
and dynintr= parameters of the ctrlprog macro instruction. 

Dynamic dispatching is intended to prevent cpu-dominant tasks from mo- 
nopolizing the CPU while i/o resources are idle and i/o dominant tasks are 
dispatchable. It is unlikely to aid environments in which most tasks are either 
CPU-dominant or i/o-dominant. 

Dynamic dispatching provides for the alteration of dispatching priorities of 
selected tasks as they are being executed. It calculates the dispatching priorities 
so that tasks can, in some cases, use the system resources more eflBciently. 
Dynamic dispatching not only alters the handling of each task as the task's 
characteristics change, but it also evaluates itself and alters itself based on its 
effectiveness in handling the tasks under its control. 

Dynamic dispatching distinguishes between i/o-bound tasks and cpu-bound 
tasks, i/o-bound tasks receive the higher priority. Initially, all tasks are designated 
as i/o-bound. As each task is dispatched, its activity is monitored for a pre- 
determined time interval. At the end of this time interval, each task is designated 
as either i/o-bound or cpu-bound. 

VSl Features and Options FEA 11 



specifications at system generation time may be changed by the operator via 
response to message ieaIOIa, issued by the nucleus initialization program ( nip ) . 
For the sysgen parameters, see the System Generation Reference publication. 
For an explanation of the responses to message ieaIOIa, see the VSl System 
Messages publication. The following shows a comparison of the sysgen param- 
eters and the message responses with a brief explanation. 



Sysgen 
Parameter 

DYNPART=(Pn-Pm) 



DYNINTR=(a, b, c, d) 



Explanation 

Specifies contiguous 
partition(s) for 
which dynamic dispatching 
will be used. 



delta value to be added to 

or subtracted from time-slice 

value at end of each 

statistics interval 

b 

lower bound of time-slice 

that may be given to a task 

c 

ratio of CPU to I/O bound 

tasks 

d 

length of statistics interval 



IEAIOIA Message 
Response 

DDG=(pn-pm) 
DDG=, may be used to 
cancel dynamic dispatching 
for the duration of this IPL. 



DDDEL=nn 



DDMIN=nnn 



DDRATIO=nnn 



DDSTAT=nnnnn 



Note: Any partition that is part of the dynamic dispatching group must not be time sliced. 



Dynamic Support System {DSS) 



Status: Announced but not available. This information is for planning purposes 
only. 

The dynamic support system (dss) is an optional interactive debugging pro- 
gram that can be used by an ibm programming system representative or other 
authorized maintenance person to help identify and correct causes of pro- 
gramming failures, dss requires the program event recording (per) hardware 
feature of the System/370. 

DSS has its own i/o capability and has access to both real and virtual storage. 
When DSS is executing, it is stand-alone and has control of the system. It can 
gain control from and return control to os/vs through its monitoring functions 
and the integral operator's console (system restart is not necessary). 

Because dss takes control from the system on each activation, time dependen- 
cies cannot be maintained. Thus, dss should not be used while a time-sensitive 
program, such as a teleprocessing or time-slice task, is running. When dss is in 
control, no other processing takes place unless dss is being used only for monitor- 
ing. In that case, normal multiprogramming continues, reduced only by the 
processing of dss. 
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The various features of the dss language include: 

Displaying and altering real storage, virtual storage, and registers. 

Providing control for the program event recording (per) hardware of the 
System/370. 

Stopping operation of the system at any instruction or per interrupt, perform- 
ing maintenance functions, and resuming operations. 

• Saving information within dss for later use or writing out the information on 
high-speed printers or on tape. 



• 



• 



Using tape or card readers for secondary command input buffers. 
Writing procedures that are often used for reiterative command sequences. 



Though changes can be m.ade by ess, they are not permanent. Any modifica- 
tions made to the system are not carried over to the next ipl. Also, dss cannot 
modify itself, ipl, or nip. 



Extract Function Made Resident 

Status: Standard. 



This function is optionally resident in os/mft but is included as a standard 
function in os/vsl. Having the function resident eliminates the necessity of bring- 
ing the routines into the supervisor transient area every time an extract macro 
instruction is issued. 

The EXTRACT macro instruction provides your program with information con- 
tained in specified fields of the task control block (tcb) of either the task that 
issued the macro instruction or, in a multiprogramming environment, one of 
its subtasks. 



Fetch Protect 



Status: Optional. Included by specifying security=fprot in the ctrlprog 

macro instruction. 

Fetch protect provides security for user data by preventing any user from 
examining the contents of another user's area of storage. This protection includes 
the entire dynamic storage area (virtual storage partitions assigned to job steps 
and system tasks) and all non-key subpools. Partitions are initially fetch 
protected by the define command. 

A combination of hardware and software support guards the non-key contents 
of a partition from disclosure to any non-key task operating in another partition. 
The PQA and sqa subpools and the nucleus are not fetch protected so that non- 
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key tasks can still reference these areas. When storage from the pqa is deallo- 
cated and returned to the partition, virtual storage management executes the 
SSK instruction, setting the fetch protect bit. 

With a 2K block fetch protected, no task can access it unless the task's current 
psw has key or the 4-bit storage key for that block. Attempts to do so result in 
fetch protection program checks. 



Graphic Programming Services (GSP, GAM) 



Status: Optional. Included by specifying the appropriate parameters in the 
GRAPHICS macro instruction. 

The graphic programming services control graphic input and output and a 
set of problem-oriented routines that are used as building blocks in the con- 
struction of graphic processing programs. The graphic subroutine package (gsp) 
allows the Fortran iv, cobol f, or pl/i f programmer to use the graphic pro- 
gramming services. 

The problem-oriented routines generate graphic instructions for displaying 
various images and alphameric information on the 2250 display unit. These 
routines function as part of the problem program and are reached by a call or 
LINK macro instruction. 



Greenwich Mean Time {GMT) 



Status: Standard. Utilized through use of the gmt parameter in the reply 

command. 

The Greenwich Mean Time feature allows the user to maintain a time clock 
that is independent of local time. This is especially advantageous for teleprocess- 
ing operations that extend across time zones. 

The TOD clock can be changed only at ipl time and requires that the gmt 
parameter be placed in the reply command. This parameter is optional, and if 
coded must give the date and time in Greenwich Mean Time. If the gmt param- 
eter is not used, the system assumes that the date and time are local and does 
not alter the tod clock. 

If the GMT parameter is used, the local time and date are maintained by estab- 
hshing an offset from Greenwich Mean Time. This offset is estabHshed at system 
generation time by using the tz parameter of the ctrlprog macro. The offset 
(local clock) can be changed during ipl in response to messages ieaIOIa and 
iee055a (see VSl System Messages) or after ipl by the set command. 

All system-issued time stamps are given in local time. To obtain gmt time 
stamps, a store clock (stck) instruction must be used. For the format of the 
STCK instruction, see System/370 Principles of Operation. 
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Identify Function Made Resident 

Status: Standard. 



This function is optional under os/mft but is standard in vsl. Having the 
identify routines resident eliminates the necessity of bringing them into the 
supervisor transient area every time die identify macro instruction is issued. 

The IDENTIFY macro instruction is used to inform the supervisor of an em- 
bedded entry point within a load module. 

After the mENTiFY macro instruction has been executed, the entry point can 
be referred to by an attach, link, xctl, or load macro instruction. 



Indexed Sequential Access Method (ISAM) 



The Indexed Sequential Access Method (isam) is comprised of the Basic In- 
dexed Sequential Access Method (bisam) and the Queued Indexed Sequential 
Access Method (qisam). See the write-ups on these two access methods in this 
section. 



I/O Load Balancing 



Status: Optionally excludable. This facility will be included in the system 

unless options=:noloadbal is specified in the schedule macro instruction. 

i/o load balancing allocates data sets to devices in such a way as to attempt 
to equalize the amount of i/o contention on each device. This facility can be 
used only for non-specific requests (that is, where no volume serial number or 
device address is specified ) . 

i/o load balancing attempts to select the best device for data set allocation by 
considering many variables. It accumulates information about the speed of the 
device, counts the number of i/o events to each device, and compares the charac- 
teristics of different devices in determining the best device to be allocated, i/o 
load balancing selects this best candidate for device allocation. If space is not 
available on that volume, the next best choice is used. 
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Job Step Timing 

Status: Standard. 



Job step timing is an optional feature under os/mft but is a standard feature 
in vsl. 

Each job step can be timed and the time limits enforced. The amount of time 
used is recorded after a job step is finished. In addition, the following are in- 
cluded in this option: the ability to request the date plus the time of day, to 
change the time at midnight, and to request, check, and cancel intervals of time. 



Machine Check Handler (MCH) 

Status: Standard. 



This program processes machine-check interruptions. Depending upon the 
severity of the malfunction, the machine check handler: 

• Restores the system to normal operation 

• Terminates tasks associated with the malfunction so the system can resume 
processing, or 

• Places the system in a wait state. 

In all cases, the machine-check handler program writes diagnostic messages 
and error records. 



Missing Interruption Checker {MIC) 

Status: Standard. Program must be started by the operator (start mic.pn). 

The MIC (missing interruption checker) is a program that polls active i/o 
operations to determine if a channel end and/or device end interruption has been 
pending for more than three minutes ( default time ) . When this occurs, or when 
the system has issued a mount request and the request has not been satisfied 
within the time period, message igf991e is issued. (See the OS/VS System Mes- 
sages publication for an explanation of the message and for operator action. ) 

After message igfQQIe is issued, the operator is given the specified time 
interval in which to respond. When that interval expires, the message is issued 
again. The action is repeated until the operator makes the necessary action. 
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The time interval can be changed through the use of a separate 8-byte csect 
(igfintvl) residing on sysI.linklib with igftmchk. To change the interval, 
iGFiNTVL must be replaced in the user's linklib as f oUows : 



//REPLACE 
//ASMLK 

// 

//ASM.SYSIN 

IGFINTVL 



//LKED.SYSLMOD 
//LKED.SYSIN 



JOB MSGLEVEL=1 

EXEC ASMFCL, 

PARM.LKED='XREF,LET,LIST,NCAL,RENr 
DD * 

CSECT 

DC CLS'OOttOOOO' 

END 

DD DSN=SYSLLINK, DISP=OLD 

DD * 

INCLUDE SYSLMOD( IGFTMGKK ) 
ENTRY IGFTMCHK 
NAMEIGFTMCHK(R) 



Multiple Walt Option 



Where: tt (two decimal characters) is the user-defined time interval. It expresses the interval 
in minutes to be used in checking for UCB conditions. Zero or non-numeric characters cause 
a default of three minutes. 



Status: Standard, 

The number of events that can be specified in a wait macro instruction can 
be extended from i to a maximum of 255. The wait macro instruction specifies 
that the task issuing the macro instruction should continue in control only after 
a particular event has occurred. An event could be the completion of an input 
or output operation or, in a multiprogramming system, the completion of another 
task. 



On-line Test Executive Program (OLTEP) 

Status: Standard. 



The On-Line Test Executive Program (oltep) is a function designed to direct 
the selection, loading, and execution of the On-Line Test sections ( olts ) . oltep, 
with the OLTS, allows the testing of input/output devices used with the system 
concurrent with the running of customer jobs. 
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Concurrent debug with oltep is not supported in the first release of os/vsl 
for systems with 144K or less of real storage. 

The OLTEp/oLT system is designed to: 

• Diagnose i/o errors 

• Verify i/o device repairs and engineering changes 

• Exercise a device requiring dynamic adjustments 

• Check the operation of i/o devices 

• Verify the integrity of customer data 

OLTEP operates as a job under os/vsl and is called by standard job control 
statements. It operates under control of the operating system at all times and 
uses the system facilities to accomplish the tests. It competes with other jobs 
in the system for the use of system facilities when running in a multiprogram- 
ming environment. 

Definition of test runs can be entered by console or non-console devices. 
Prompting is available on consoles to assist in defining tests to be run. 

IBM Field Engineering will supply the olts to the customer on magnetic tape 
or cards. The olts must be reformatted and link edited into a partitioned data 
set in order to be used under the operating system. 

OLTEP must normally be executed in the non-pageable (virtual=real) area of 
real storage. It requires a minimum virtual partition of 64K and 36K bytes of 
real storage. The logout analysis program, which runs under oltep similar to 
an OLT, does not require virtual=real storage. 

The initial release of oltep must run in the virtual=real storage area and is 
not supported on systems with less than 144K of real storage. 



Program Conlrolled Interrupt (PCI) 



Status: Optional. Included by specification of fetch=pci in the ctrlprog 
macro instruction. 

The program controlled interrupt (pci) facility permits the program to cause 
an i/o interruption during execution of an i/o operation, pci provides a means 
of alerting the program of the progress of chaining during an i/o operation. 

pci fetch is able to bring a program into storage with only one seek of the 
disk if: 

• A buffer is always available for relocation dictionaries. 

• No errors occur during the i/o operation. 

• No cylinders are crossed while bringing in the program. 

• The speed of the central processing unit allows pci to modify the channel com- 
mand word before it reaches the channel. 



FEA 18 OS/VSl Planning and Use Guide 



An additional wait and seek are required each time a buffer is not available. 
A seek is required each time an error occurs or a cylinder is crossed. If the 
speed of the central processing unit does not allow pci to perform its function in 
time, the number of seeks needed by the standard fetch are required. 



Queued Indexed Sequential Access Method (QISAM) 



Status: Optional. Included when acsmeth=isam is specified in the datamgt 
macro instruction. 

Sequential and direct processing are provided by the Indexed Sequential 
Access Method (isam). Records are maintained in control field sequence by 
key. The system maintains a multilevel index structure that allows retrieval of 
any recorvi uy its Key. Auditions can ue mau.e to an existmg isam uata set without 
rewriting the data set. 

The Queued Indexed Sequential Access Method (qisam) is used to create 
an indexed sequential data set or to retrieve and update records sequentially 
from such a data set. Synchronization of the program with the completion of 
input/output transfer, and record blocking/deblocking are automatic, qisam 
is also used to reorganize an existing data set. 



Queued Sequential Access Method (QSAM) 

Status: Standard. 



In the Queued Sequential Access Method (qsam), logical records are re- 
trieved or stored as requested. The access method anticipates the need for 
records based on their sequential order, and normally will have the desired 
record in storage, ready for use, before the request for retrieval. When writing 
data, the program normally continues as if the record had been written im- 
mediate!^' althou^'h the access method routines ma^^ block it with other lo^'ica! 
records and defer the actual writing until the output buffer has been filled. As 
with BSAM, automatic translation between ebcdic and ascii codes is provided 
for magnetic tape labels and record formats. 



Reenterable Load Modules Made Resident 
Resident Access Method Routines 

Status: Standard. 



Reenterable load modules from sysI.linklib and sysI.svclib and reenterable 
access method modules from sysI.linklib are resident under vsl. Having these 
modules resident eliminates the necessity of bringing them into storage when- 
ever they are required. 

Standard lists are used during ipl to indicate the load modules that are to 
be made resident. See the Resident Routines Options section for a complete dis- 
cussion of this function. 
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Shared DASD 



Status: Optional. Included by specification of featuee=shared in the 
lODEViCE macro instruction. 

Up to four central processing units can access the same direct access device 
concurrently, depending upon the device configuration. 

See the Shared Direct Access Device Option section for a complete discussion 
of this function. 



SPIE Routines Made Resident 

Status: Standard. 



The routines that make up the Set Program Interruption Element (spie) func- 
tion are resident in storage in vsl. This function is optionally resident in os/mft. 
Having the function resident ehminates the necessity of bringing it into storage 
whenever the spie macro instruction is issued. 

The SPIE macro instruction specifies the address of a routine to be used when 
specified program interruptions occur in the task that issued the macro instruc- 
tion. 



Storage Protection Option 



Status: Standard. 

This is an optional feature under os/mft but is standard in vsl. 

Storage protection keys are assigned to 2K areas of storage that are designated 
for use by either the system (storage protection key of 0) or problem programs 
(storage protection keys of 1-15). This feature prohibits the modification, by a 
problem program, of areas of storage other than those identified with the 
problem program's storage protection key. The system has access to all allocated 
storage protection keys and may, on occasion, use non-key areas. 



System Management Facilities (SMF) 



Status: Optional. Included (or excluded) by specification of the appropriate 
parameter in the smf= operand of the schedulr macro instruction. 

The System Management Facilities (smf) collect and optionally record system, 
job management, and data management information. They also provide control 
program exits to installation-suppHed routines that can periodically monitor the 
operation of a job or a job step. 
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SMF collect such information as: 

System configuration 

Job and job step identification 

CPU wait time 

CPU time used by each job and job step 

Virtual or real storage requested by each job step 

Virtual or real storage used by each job step 

Paging statistics on a job step and system basis 

i/o device use by each job step 

Temporary and non-temporary data set use by each job and job step 

Temporary and non-temporary data set status 

Status of removable direct access volumes 

Input count by each job and job step 

Output count by each job 

Output writer records by each job 

Allocation recovery records by each job 

VARY ONLINE and OFFLINE rccords 

It is possible to suppress the writing of all, or of selected, smf records at ipl 
time. 

The SMF exits to installation-written routines allow certain parameters to be 
passed to them to identify the job and job step being processed and to provide 
accounting and operating information. These exit routines can cancel jobs, write 
records to the smf data set, open and use their own data sets, and suppress the 
writing of certain smf records. 



Telecommunications Option 



:iiaius: upnonaL mciuaea oy specmcauon or jbtam ana/ or tcam in tne 
datamgt macro instruction. 

The telecommunications option is comprised of two access methods, the Basic 
Telecommunications Access Method (btam) and the Telecommunications Ac- 
cess Method (tcam). 

BTAM provides the basic facilities required to process a telecommunications 
program. These include facilities for creating terminal lists and for performing 
the following operations: 

Initiating and answering calls to and from terminals on switched networks 

Polling and addressing terminals on non-switched multi-point lines 

Changing the status of terminal lists 

Transmitting and receiving messages 

Code translation 

Retransmitting messages which are received with detected errors 

Providing on-line terminal test facilities 

Keeping error statistics 
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BTAM supports binary synchronous communications on a variety of low, 
medium, and high speed start/stop devices. 

BTAM supports binary synchronous communications over non-switched (leased 
or private direct connection) and switched (dial) networks in a System/370 to 
terminal communication. 

Optional communication serviceability facilities are available in btam. They 
include error recovery procedures, diagnostic error information, error counts, 
and on-line terminal tests. It is recommended that these facilities be included, 
since they increase system availability. 

os/vsl BTAM supports the same functions as os btam and requires no addi- 
tional programmer training. The user is cautioned concerning internal changes 
he may have made in os btam. Similar changes will be required in vsl btam. 

The Telecommunications Access Method (tcam) is a general purpose tele- 
processing support program. It provides: 

• A regionalized, general-purpose teleprocessing access method with facilities 
that permit exchange of data between a central System/370 and remote 
terminals. 

• A control program designed to optimize the allocation and scheduling of a 
computer's resources in a real-time teleprocessing environment. 

• A high-level language composed of macro instructions designed specifically 
to facilitate the construction of a teleprocessing network control program. 

tcam provides unified management of terminal devices, local and remote, 
including binary synchronous communication devices, through a single message 
control program. The tcam application program interface has been defined to 
provide maximum compatibility with bsam ( read/\vtrite level) and qsam 
(get/put level), yet provide the ability to identify or specify source and destina- 
tion of terminal i/o. Network control functions may be provided in an application 
program able to issue tcam operator control commands. 

Teleprocessing applications using tcam are constructed by providing a mes- 
sage control program and one or more tcam apphcation programs. 

The tcam message control program serves as an interface between remote 
terminals, user-written application programs, and secondary storage devices on 
which messages are queued until their destinations are available to receive 
them. The message control program controls the flow of messages to and from 
the terminals, application programs, and queuing devices in a manner that 
optimizes allocation and scheduling of the computer's resources. 

tcam permits the user to code one or more application programs and inter- 
face these with the message control program. Application programmers are 
insulated from the teleprocessing environment. They issue ordinary gets and 
PUTS or READS and writes to move data between the message control program 
and application program work areas. 

TCAM application programs can be sam compatible, and may be debugged in 
a non-teleprocessing environment using bsam or qsam as the access method. 
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Time-Slicing Facility 



with a tape, card reader, disk, card punch, printer, etc. as i/o devices. Once de- 
bugged, many application programs can be plugged into tcam without reas- 
sembly by changing a single job-control statement. The user can specify that 
either messages or user-defined records be transferred when he issues his 
get/read or put/write macros. 

TCAM offers an extensive set of service facilities including: 

• A set of operator commands that allow the user to determine the status of his 
teleprocessing system and alter, activate, or deactivate portions of that sys- 
tem by entering appropriate commands from the system console, remote 
terminals, or application programs. 

• A checkpoint/restart facility that allows the user to specify that his message 
control program environment be restored following system failure or close- 

• A facility for selectively logging incoming or outgoing messages or message 
segments. 

• Comprehensive debugging aids, including error-recovery and event-recording 
facilities, and utilities that permit debugging information to be dumped to 
tape or disk and then printed out. 

• An on-line test facility that allows the user to test transmission control units 
and remote terminals without closing down the message control program or 
deallocating the device being tested. 

OS TCAM message control programs must be reassembled to run in the os/vsl 
environment. This reassembly allows the message control programs to benefit 
from the virtual storage capability of vsl. Under vsl, tcam runs as a subsystem 
in a virtual partition. Certain tcam elements, such as the buffer pool, i/o ap- 
pendages, control blocks, and tables are fixed in real storage for the duration 
of the tcam task. 



Status: Optional. Invoked by specification of the appropriate parameters in 
the TMSLiCE= operand of the ctrlprog macro instruction. 

When the time-slicing facility is included in the system, you can establish 
a group of partitions or tasks ( called a time-slice group ) that are to share the 
use of the cpu, each for the same fixed interval of time. This is done for jobs 
scheduled into a group of consecutive partitions that have been defined as the 
partitions to be used for time sHcing. 

The priority of a job can be changed by the chap macro instruction so that its 
priority will fall within the range of the priorities for the partitions defined for 
time slicing. This job will then be handled in the same manner as the other 
jobs in the time slice group. 

When a member of the time-slice group has been active for the fixed interval 
of time, it is interrupted and control is given to another member of the group, 
which will, in turn, have control of the cpu for the same length of time. In 
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this way, all member tasks are given an equal slice of cpu time, and no task 
or partition within the group can monopolize the cpu. 

Only partitions that are assigned to the time-sHce group will be time-sliced, 
and they are time-sliced only when the first partition in the group is the highest 
priority ready task. Dispatching of the partitions continues within the group 
until all the partitions are in a waiting state, or until a partition with a higher 
priority is in a ready state. 

The group of tasks to be time-sliced (selected by priority or partition range) 
and the length of the time slice are specified at system generation time in the 
CTBLPROG macro instruction. This can be modified in vsl through the define 
command. Any task or partition in the system that is not defined within the time- 
slice group is dispatched under the current priority structure; that is, the task 
or partition is dispatched only when it is the highest priority ready task or par- 
tition on the TCB queue. The maximum number of milliseconds, a number speci- 
fied from a range of 20 to 9999, is the amount of time that each ready task 
is to have control of the cpu during one pass through the group. 



Trace Option 



Status: Optional, Included when the trace= 
CTRLPROG macro instruction. 



parameter is specified in the 



Transient SVC Table 



A tracing routine aids in debugging and maintenance of the system. 

The tracing routine stores information pertaining to start i/o ( sio ) instruction 
execution, supervisor (svc) interruptions, external interruptions, program check 
interruptions, and i/o interruptions in the trace table. When the table has been 
completely filled, the succeeding entries overlay the existing ones. 

During system generation, only the size of the table is specified. However, when 
this system generation parameter is specified, the trace program routines are 
also included as part of the control program. 



Status: Optional. Included when options=trsvctbl is specified in the 
CTRLPROG macro instruction. 

The relative track address (ttr) of all transient supervisor (svc) routines are 
included as part of the resident table of control program svc routines. (See the 
description in Types 3 and 4 SVC Routines Made Resident in this section. ) 
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Types 3 and 4 SVC Routines Made Resident 



Status: Optional. Included when kesident=trsvc is specified in the ctrlprog 
macro instruction. 

Modules of types 3 and 4 supervisor ( svc ) routines can be made permanently 
resident in storage. 

Types 3 and 4 svc modules are loaded and made resident at ipl time. When 
this option is specified, the transient svc table option is assumed. The svc table 
is a table containing the relative track addresses of all transient svcs. This table 
is also stored in the resident portion of the control program. 

The names and sizes of the types 3 and 4 svc routine modules are given in the 
OS/VSl Storage Estimates publication. ( See also the preceding description Tran- 
sient SVC Table and the Resident Routines Options section of this publication. ) 



User Modify Logical Cylinder Facility 



Status: Optional. Included by specification of the alcunit parameter in the 
jESPARMs member of sysI.parmlib. 

The user modify logical cylinder facility allows you to define the unit of alloca- 
tion for spooling. A default value for logical cylinder definitions set at system 
generation time allows for approximately 28K of dasd work space per allocation. 
These values are adequate for an installation whose spool data sets (jcl, sysin, 
SYSOUT, etc ) vary in size. If your installation consistently has jobs with small spool 
data sets and uses less than 28K, dasd work space is wasted. This facility allows 
you to specify a smaller unit of allocation, increasing spool availability. If your 
installation consistently has jobs with large spool data sets (using more than 
28K), the default logical cvlinder definitions could cause extra allocation pro- 
cessing. Defining a larger unit decreases the number of spool allocation calls. 

To modify the logical cylinder definitions, specify the unit of allocation in 
bytes via the alcunit parameter of the jesparms member of sysI.parmlib. The 
system converts the byte value to a value in tracks for each spool device type. 
The default value, 28,672 bytes, allows for the following logical cylinder defini- 
tions : 

• For 2314 or 2319, a logical cylinder is 5 tracks. 

• For 3330 or 2305-2, a logical cylinder is 3 tracks. 

The formula used by the system to convert the byte-cyHnder definition to tracks is : 

ALCUNIT 
BUFSIZE ' buffers per track 
where 
ALCUNIT is the specification of the spool allocation unit in bytes via the alcunit 
parameter in the jesparms member of sysI.parmlib. 
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BUFsizE IS the spool buffer size as specified in the bufsize parameter in the 
JES SYSGEN macro or the jesparms member of sysI.parmlib. 

buffers per track is the buffer-per-track count for the volume. 

ALCUNIT must be large enough so that the logical cylinder will contain at least 
one logical cylinder map (see the Master Cylinder Map size formula in the sec- 
tion on SYsl.SYSPOOL in the System Generation Reference manual). It must also 
be small enough that, when it is converted to tracks, it is less than 256 tracks. 

The following is an example of the jcol and control cards that might be used 
to change alcunit in the jesparms member of sysI.parmlib to 5,000 bytes: 



//PARMSC JOB MSGLEVEL = 1 








//SG1 EXEC PGM = IEBUPDTE,PARM = NEW,C0ND = (4,LT) 






//SYSPRINT DD SYSOUT = A 








//SYSUT2 DD DISP = 0LD,DSN = SYS1.PARMLIB,UNIT= 


2314,VOL=SER 


= AOS102 


//sysin dd data 








./ ADD name=jesparms,level=oi,ust=all,seqfld = 


= 738 




./ NUMBER NEW1 = 1,INCR = 5 








BUFSIZE=436,NUMBUFS = 7,STEPWTP = 15, 






00000001 


SWDSLMT = 15,SPOLCAP = 80,WTLRCDS200, 






00000006 


RDR = (R = 1,Y = 5,B=0),JOUTLIM = 5000, 






00000011 


WTR = (W = 1,U=5,Z = 10,B = 132), 






00000016 


ALCUNIT = 5000, 






00000021 


SPOLVOL = (SYSRSM) 






00000026 

t 


col 10 


col 73 



Note: When ALCUNIT has been varied, system restart cannot be performed. 



User-Added SVC Routines 



Status: Optional. Included by specification of the appropriate parameters 
in the svclib macro instruction. 

User- written supervisor (svc) routines can be added to the control program. 

All SVC routines, whether they are to be transient or resident, must be listed 
in the operand of the svctable system generation macro instruction. 

Any resident svc routines that are to be added must be specified in the system 
generation besmods macro instruction. The fixed storage requirement is in- 
creased by the total of the sizes of the routines that are going to be added 
plus the size of the control information. 
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Any transient svc routines that are to be added must be specified in the 
svcLiB system generation macro instruction in the operand. In this case, only 
the size of the control information is added to the fixed storage requirements. 

Nonstandard error routines can be one of the types of routines that are 
added. User-written routines must have a value from 220 to 229. This value is 
the sufiix of the name igeOO by which the error routine is named in sysI.svclib. 

See the section Adding SVC Routines to the Control Program in this publi- 
cation for a complete discussion of this feature. 



Validity Check Option 



This is an optional feature under os/mft, but is standard in vsl. Extra validity 
checking is included in the system to determine whether addresses are located 
within proper boundaries. The validity checking is provided for the wait, post, 
and getmain/feeemain modules. The checking for wait also checks for the 
number of events. 



Virtual Storage Access Method (VSAM) 

Status: Announced but not available. 



The Virtual Storage Access Method, vsam, is announced but not available. 
VSAM is an access method for use with direct access storage devices on ibm 
System/370 with vs. vsam creates and maintains two types of data sets. One is 
sequenced by a key field within each record and is called a key-sequenced data 
set. Data records are located by using the key field and an index that records 
each key field and the address of the associated data, similar to isam. The other 
is sequenced by the time of arrival of each record into the data set and is 
called an event-sequenced data set. Data records are located by using the records 
displacement from the beginning of the data set. The displacement is called 
the relative byte address (rba). The rba is similar to the relative block address 
used with bdam. 

VSAM stores, retrieves, and updates user data records in these types of device 
independent data sets, vsam stores data records in a new format designed for 
long term data stability and for data base applications. Data in both types of 
data sets can be accessed either sequentially or directly. 

vsAM enhances many isam capabilities including device independence, con- 
current processing, data portability, and kinds of accessing supported. It pro- 
vides additional password security protection, vsam creates and maintains sepa- 
rate catalogs that contain specilized information about each vsam data set and 
are used to link a data set to its index, vsam includes a multifunction utility 
program that defines, deletes, prints, copies, and provides backup and portability 
of vsam data sets and maintains the separate catalogs. An interface routine to 
allow most isam programs access to vsam data sets is also provided. For a more 
detailed explanation of vsam, see the OS/YS Virtual Storage Access Method 
(VSAM) Planning Guide, GC26-3799. 
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Volume Statistics Facility 



Status: Optional. Included when smf^full is specified in the schedulr 
macro instruction with appropriate operands for the esv= and eva= para- 
meters. 

The volume statistics facility is used only for magnetic tape volumes with 
or without labels. It provides two functions, either or both of which can be 
specified at system generation time in the schedulr macro instruction. 

One function is error statistics by volume (esv). It is intended primarily to 
be used with labeled volumes, but will handle an unlabeled volume if the serial 
number is given to the operating system. Statistics about the number of read 
or write errors and the system and unit on which the volume is located are 
recorded. 

The other function is error volume analysis (eva). It is intended primarily to 
be used for unlabeled or nonstandard labeled volumes. It monitors the number 
of read or write errors based on the limits you provide at system generation time. 

The error statistics by volume (esv) collects a set of statistics for each labeled 
tape volume whenever the volume is open. An unlabeled tape volume can be 
handled if the serial number has been supplied to the operating system. 

If Esv^SMF is specified at system generation time, the statistics are accumu- 
lated on the system management facility (smf) data sets sysI.manx and 

SYSl.MANY. 

If Esv=coN is specified or if esv is not coded, an abridged version of the sta- 
tistics is printed on the console. This occurs at end-of-volume or when the tape 
volume is closed. 

You can provide your own recording routine. esv=con must be specified, or 
the keyword parameter can be omitted because the default is con. The ucbs, in 
the proper format, are constructed at system generation time. You can provide 
your own access method, using svc 91, specify your own record format, and 
select your own recording data set. If you use the record 21 format instead of 
your own, you can use the ifhstatr utility to print out the statistics. 

The error volume analysis (eva) acts as a monitor about the number of read 
and write errors for unlabeled or nonstandard labeled tape volumes. You provide 
the maximum limits for read errors and/or write errors and, if the maximum 
is reached or exceeded, a message, iea620i, is printed on the console. 
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JES Reconfigurability 



This section explains how to temporarily modify, or 
reconfigure, the Job Entry Subsystem (jes) param- 
eters which were specified for your system at sysgen 
time. The temporary modification occurs at ipl time 
and will be effective until the next ipl. 



SecffOfi Outline 



JES Reconfigurability JES 1 

JES Reconfigurability JES 3 

JESPARMS Member in SYSl.PARMLIB JES 3 

JESPARMS Entries JES 3 



JES Reconfigurability JES ] 
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JES Reconfigur ability 



JES reconfigurability permits you to make temporary modifications, at ipl time, 
to the JES parameters which were specified at sysgen time. To make permanent 
updates to the system jes values, you must do a new sysgen. 



JESPARMS Member in 
SYSl.PARMLIB 



The JESPARMS member in sysI.paemlib contains the jes options or default values 
that were specified at sysgen. This member also provides an example for you 
to use in re-specifying any or all of the jes parameters. The parameters in 
JESPARMS are checked at ipl time by a master scheduler initialization routine. 
If any errors are detected during the check, a message is written on the console, 
indicating the error and the jes values specified at sysgen are used by the sys- 
tem. If no errors are detected, the jes values specified in jesparms will tem- 
porarily override those specified at sysgen. If the jesparms member is deleted, 
the JES values specified at sysgen are used. 

The sysgen process uses the iebupdte utility program to place jesparms 
in SYsl.PARMLiB. This utility is also used to maintain and update jesparms. 



JESPARMS Entries 



Each JESPARMS entry must be an 80-byte record using positions 1 through 71 
to contain the jes parameters, and the optional information field, jes parameters 
can start in any position in the record, but they must be completed, with the 
exception of the spolvol parameter, on the same record. All parameters must 
be separated by a comma. If an optional information field is present in the 
record, it must be separated from the parameter(s) by at least one blank position 
following the comma. 

During the check at ipl time, the parameters are scanned until: 

1. An error condition is found 

2. A parameter not followed by a comma is found 

3. The end of the data set is reached. 

If either of the first two conditions occur, the remaining parameters are not 
checked. 



JES Reconfigurability JES 3 



Two examples of routines to modify the jes values on a temporary basis follow. 
For a complete description of the jes parameters, see the VSl SYSGEN publica- 
tion. 



//STEP1 


EXEC 


//SYSPRINT 


DD 


//SYSUT1 


DD 


//SYSUT2 


DD 


//SYSIN 


DD 


./ REPL 


REPL 


./ NUMBER 





PGM=IEBUPDTE,PARM=MOD 

SYSOUT=A 

DSNAME = SYS1.PARMLIB,V0L = SER = V0LID1,UNIT=2314,DISP = 0LD 

DSNAME = SYS1.PARML1B,V0L = SER = V0LID1,UNIT = 2314,DISP = 0LD 

DATA 

NAME = JESPARMS,LEVEL = 01,LIST=ALL,SEQFLD = 738 

NEW1 = 1,INCR = 5 
BUFSIZE = 600, *»JES PARAMETER OPTIONS** 

NUMBUFS = 15, 
STEPWTP = 20, 
SWDSLMT = 30, 
WTLRCDS = 200, 
JOUTL1M = 5000, 
RDR = (R = 2,Y = 5,8 = 9999), 
WTR = (W=1,U = 0,Z = 6,B = 9999), 
SPOLCAP = 20, 

SP0LV0L= (000000,1 11111 ,222222,333333,444444,555555,666666,777777, 
888888,999999) 



Note that the spolvol parameter is the only parameter that can span records. 
All other parameters must be started and completed on the same recca"d. 



//STEP1 


EXEC 


PGM= IEBUPDTE,PARM = MOD 


//SYSPRINT 


DD 


SYS0UT=A 


//SYSUT1 


DD 


DSNAME = SYS1.PARMLIB,V0L = SER = V0LID1,UNIT=2314,DISP = 0LD 


//SYSUT2 


DD 


DSNAME = SYS1.PARMLIB,V0L = SER = V0LID1,UNIT=2314,DISP = 0LD 


//SYSIN 


DD 


DATA 


./ REPL 


REPL 


NAME = JESPARMS,LEVEL = 01,LIST=ALL,SEQFLD = 738 


./ NUMBER 




NEW1=1,INCR = 5 




BUFSIZE = 600,NUMBUFS=15,WTLRCDS = 200, 




JOUTLIM = 5000,STEPWTP = 20,SPOLCAP = 20, 




SWDSLMT = 30,SPOLVOL= (000000,1 1 1 1 1 1,222222,444444,555555), 






••CONTINUATION OF SPOLVOL PACK** 




RDR = 


(R = 2,Y = 5,B=9999), 


/• 


WTR = 


(W=1,U = 0,Z = 6,B = 9999) 



Note that some parameters are combined on one record and that optional infor- 
mation can be placed in the positions following the parameter and at least one 
blank. 
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Job Queue Format 



The job queue format is specified when the system 
is generated and may be altered during subsequent 
system start procedures. Formatting consists of speci- 
fying the number of queue records in a job queue 
logical track, specifying the number of queue records 
to be reserved for each initiator, and reserving queue 
records needed to start at least one initiator and one 
writer. 

This section provides guidelines for estimating: 

• The number of queue records in a job queue 
logical track. 

• The number of queue records to be reserved for 
use by an initiator. 

• The number of queue records to be reserved to 
start at least one initiator and one writer. 
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VSl Job Queue Formatting 



The basic element of the system job queue (the data set sysI.sysjobqe) is a 
176-byte record, the queue record. The total number of queue records available 
is fixed by the space allocated to the sysI.sysjobqe data set. Queue records 
contain some of the tables and control blocks developed by the reader, inter- 
preter, and initiator control program routines. 

Lack of queue records is not critical for a reader routine. Processing of a 
reader is suspended until queue records become available, at which time pro- 
cessing is resumed. An initiator, however, must have sufficient queue records 
available to complete the initiation and running of a job. Because one or more 
readers and one or more initiators may be concurrendy active, steps must 
be taken to ensure that queue records are available to each initiator started, so 
that it may complete its operation. The main function of job queue formatting 
is to reser/e queue records for initiator use. 

To format the job queue, you must: 

1. Designate the address of the device on which sysI.sysjobqe resides, and 
indicate that it is to be formatted. 

2. Designate: 

a. The number of queue records to be contained in a job queue logical 
track. A logical track consists of a header record (20 bytes) plus the 
designated number of queue records. Queue records are assigned in 
terms of logical tracks. 

b. The number of queue records to be reserved for use by an initiator. Each 
initiator is allocated this number of records. 

c. The number of queue records to be reserved to start a writer and an 
initiator if queue space becomes critical. 

The balance of the queue (total queue records less the reservations in items 
2b and 2c) is the maximum available for use by the reader(s). 

Specify initial values for items 2a, 2b, and 2c in the schedulr macro instruc- 
tion parameters jobqfmt, jobqlmt, and jobqtmt, respectively. The System 
Generation publication describes the procedure. 

The service aids program imcjobqd provides a formatted dump of the entire 
job queue, or selected portions of it. The formatted dump includes the master 
queue control record (qcr) which contains the physical parameters of the job 
queue. For a complete description of imcjobqd see the appropriate Service Aids 
publication. 

No comprehensive, foolproof formulas exist for calculating values of jobqfmt, 
jobqlmt, and jobqtmt. The values to be estimated depend on the requirements 
and structure of jobs to be presented to the system. The rest of this section 
provides some basic guidelines for your use in determining these values. 



logical Track Size-JOBQFMT 



This specification affects the efficient use of queue records. Queue space is 
allocated in terms of logical tracks. Unused records in a logical track are not 
available for use for other jobs. Therefore, an overly large logical track size 
results in wasted queue records and the reduction of job queue capacity. Con- 
versely, a small logical track size can result in decreased performance if most 
jobs require frequent assigning of a new logical track. 
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The distinction needed here is between problem program and system tasks. 
In the context of a discussion of the queue space used, all generalized start jobs 
are considered system tasks. The job queue space required for a problem pro- 
gram is quite small, whereas the space needed for a system task is considerably 
larger. Thus, the factor to consider in picking a value for this parameter is the 
number of system tasks run, as compared to the number of problem programs. 

This trade-off is best summarized as follows: 

• The larger the logical track size, the less frequently new tracks are allocated 
in handling system tasks, but space wiU be wasted in handling problem pro- 
grams. The smaller the logical track size, the more eJBSciently job queue 
space will be used, but the overhead in processing system tasks will be in- 
creased. 

• The range of possible values is from 5 to 255. The default value is 5. This 
minimum size is suflBcient to contain the entire input queue entry for a 
problem program. This size also allows up to five data sets per sysout class 
other than the message class and four data sets in the message class without 
requiring the allocation of more than the minimum number of tracks needed 
for any job. This minimum is x-f-1 tracks, where x equals the number of 
SYSOUT classes used by the job. The default of five, therefore, results in maxi- 
mum space usage of the queue. A larger size would only be needed if the 
generalized start function is used frequenty, and the installation wants to 
decrease the number of allocations needed for the system tasks on the queue. 

You may, as a starting point, wish to use the default value for jobqfmt (five 
queue records ) . 



Reserving Initiator Queue Records— JOBQLMT 



The value specified for this parameter must take into account the possibility of 
tables being written to the job queue by components other than the interpreter. 
During normal job execution, this value should be equal to swdslmt (in the jes 
sysgen macro) plus the product of the logical track size (jobqfmt) times the 
average number of sysout classes used by a job. However, if the user intends 
to use automatic restart in the system, this number must be substantially in- 
creased. This is because of the conditions under which restart functions. The 
job to be restarted must be reinterpreted. Therefore, a set of interpreter records 
is needed. Also, the restart reader needs ten records for its own use. Finally, 
if automatic checkpoint/restart is being used, some restart housekeeping records 
are needed. These requirements can be summarized by the following formula: 

JOBQLMT = L + S + lOA + 12A 
where : 

L = value of JOBQLMT if automatic restart is not used. 
S = size of SWADS, in records. 

A = number of times a job may be automatically restarted. 
10 = step restart housekeeping records (needed also for checkpoint). 
12 = Checkpoint/restart housekeeping records (needed also for checkpoint in addition 
to the ten needed for step restart). 

If jobs with automatic restart may be held for operator restart, the jobqlmt 
requirement is increased even further, because the system must maintain both 
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the queue records and the housekeeping records for the held jobs until they 
have completed processing and are written. The formula then becomes: 

JOBQLMT = (H + 1) (L + S + lOA + 12A) 
where: 

H = number of jobs that may be held at any one time. 

Other terms are as previously described. 

When a start initiator command is issued, a check is made to see if enough 
free logical tracks are available to provide the required number of queue records 
for the initiator. If not, the command is rejected. 

Each time an initiator is started, the number of records reserved for an 
initiator is added to the total number of records reserved for active initiators. 
For example, if four initiators have been started and the number of records re- 
served for each initiator is 25, the number of records reserved for starting a 
writer and initiator if queue space becomes critical is 80, then the total number 
of records reserved is 205. This total includes 25 records reserved for each in- 
itiator, 80 records reserved for starting a writer and an initiator if queue space 
becomes critical, and 25 records reserved as a basic threshold. 



Reserving Records to Start a Writer and an Initiator— J OBQTMT 



When the reserves of queue space are becoming critical, space must be avail- 
able to get system tasks started (especially the writer since it returns queue 
records to the system )= Thus, to ensure availability of this space, the value of 
jobqtmt should be the number of records needed to start the writer and the 
initiator. The amount needed to start each of these tasks may be estimated by 
following the formula for swads size (see the OS/VSl Storage Estimates publica- 
tion) taking into consideration that the jcl from the start command and the 
cataloged procedure must be interpreted. The queue space needed for input 
and output queue entries is automatically added by the queue manager. 
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Message Routing Exit Routines 



This section provides detailed information on how to 
write user exit routines that modify the routing and 
descriptor codes of wto or wtor messages for any 
os/vs operating system that has the Multiple Console 
Support Option (mcs). Information is provided on 
inserting this exit routine into the resident portion of 
the control program. In addition, a description of 
the characteristics and configuration of mcs is sup- 
plied. 

Documentation of the internal logic of the super- 
visor and its relationship to the remainder of the con- 
trol program can be obtained through your ibm Branch 
Office. 
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Charactetist'ics of MCS 

Multiple Console Support (mcs) is an option of vsl that routes messages to 
different functional areas according to the type of information that the message 
contains. In mcs, a functional area is defined as one or more operator's consoles 
that are doing the same type of work, (Some examples of functional areas are: 
(1) the tape pool area, (2) the disk pool area, and (3) the unit record pool area.) 
Each WTO and wtor macro instruction is assigned one or more routing codes 
which are used to determine the destination of die message. There are 16 routing 
codes that can be used. When the message is ready to be routed, the routing 
codes assigned to the message are compared to the routing codes assigned to 
each console. If any of the routing codes match, the message is sent to that 
console. (For descriptions and definitions of the routing codes see the Routing 
and Descriptor Codes publication.) 

If the standard routing codes provided on application and system messages 
do not cover special situations at your installation, the routing codes used on 
the message can be modified by coding a user exit routine. The exit routine re- 
ceives control prior to the routing of messages so that you can examine the 
message text and modify the message's routing and descriptor codes. The sys- 
tem uses your modified routing codes to route the message. Descriptor codes 
provide a mechanism for message presentation and deletion and are explained 
later in this section. 

Automatic console switching occurs when permanent hardware errors are 
detected. Command initiated console switching is provided to permit restructur- 
ing of the system console configuration and the hard copy log by system operators. 
Consoles can be moved into or out of functional areas at any time during system 
operation. 

A hard copy log option is provided to record messages, operator and system 
commands, and operator and system responses to commands. The hard copy log 
may be a console device or it may be the system log (syslog). The number and 
type of messages recorded on the log is also optional. Your installation may 
wish to record a selected group of messages, or it may wish to record all messages. 
If commands are recorded, the system automatically records command responses. 

Information about res support for wro and wtor appears in the System Macro 
Instructions (SMI) section of this publication. 

Writing a WTO/WTOR Exit Routine 

You write a wto/wtor exit routine to modify the standard routing codes and 
descriptor codes. This routine will be part of the control program. If a message's 
routing code field is used by the operating system to route the message, your 
routine receives control prior to the routing of the message. When your routine 
receives control, register 1 contains a pointer to the first word of the message 
text. The message text field is 128 bytes long; followed by a 4-byte routing code 
field and a 4-byte descriptor code field. Your exit routine may examine but not 
modify the message text. 

A message is sent to only those locations specified in the modified routing 
codes. All messages with modified routing codes are sent to the hard copy log when 
the log is included in the operating system. When the log is not included, the 
exit routine must not suppress messages that contain a routing code of 1, 2, 3, 4, 
7, 8, or 10 since messages with these codes are necessary for system maintenance. 
Message suppression is turning off all routing codes of a message, causing the 
message to be discarded, wto messages can be suppressed. If a wtor message 
is suppressed, it is sent to the master console by the operating system. 
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Conventions 


Requirements 


Reference 
Code 


Part of resident control program 


Yes 




Size of routine 


Any size 




Reenterable routine 


Optional, but must be serially reusable 


1 


May allow interruptions 


Yes 


2 


Nanne of routine 


Must be lEECVXIT 




Disposition of general registers 


Registers must be saved at entry and 
restored prior to returning 




Fornnat of text and codes 


Provided through the DSECT lEECUCM 


3 


May issue WAIT, XCTL, WTO or 
WTOR macro instructions 


No 




Method of abnormal termination 


None 


4 


Exit from routine 


RETURN macro instruction 





Figure MSG 1. Programming Conventions for WTO/WTOR Exit Routines 



Programming Conventions 
for WTO/WTOR Exit 
Routines 



The programming conventions for the wto/wtor exit routine are summarized in 
Figure msg 1. Details about many of the conventions are in the reference notes 
that follow that figure. The notes are referred to by the numbers in the last 
column of the figure. 



Reference 
Code 



Reference Notes 

If your exit routine is to be reenterable, you cannot use macro in- 
structions whose expansions store information into an inline para- 
meter list. 



You should write your exit routine so that program interruptions 
cannot occur. If a program interruption occurs during execution 
of the exit routine, the routine loses control and the communications 
task is terminated. 

DSECT lEECucM provides the format of the message text, routing codes 
and descriptor codes. The pointer in register 1 points to the first 
word of the message text, ucmmstxt. The format is: 



UCMMSTXT 


Message Text (128 Characters - 


- padded with blanks) 


UCMROUTC 


Routing codes (4 bytes) 




UCMDESCD 


Descriptor codes (4 bytes) 





DSECT ieecucm is Contained in sysI.amodgen 



System messages have a message code as the first seven characters 
of the message text. This code may be examined to aid in identifying 
system messages, but it must not be modified. 
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Reference 
Code 



Reference Notes 

The ucMROUTC field contains the routing codes. A bit setting of 
"1" indicates that the wto or wtor was assigned that particular 
routing code. Bit assignments and their meanings are: 



Bit 

Byte 
Bit 



Bit 
Bit 
Bit 
Bit 
Bit 
Bit 



Bit 7 

Byte 1 
Bit 
Bit 1 
Bit 2 
Bit 3 
Bit 4 
Bit 5 
Bit 6 
Bit 7 



Assignment Meaning 

Routing code 1 Master console 

Routing code 2 Master console informational 

Routing code 3 Tape pool 

Routing code 4 Direct access pool 

Routing code 5 Tape library 

Routing code 6 Disk library 

Routing code 7 Unit record pool 

Routing code 8 Teleprocessing control 

Routing code 9 System security 

Routing code 10 System error/maintenance 

Routing code 11 Programmer information 

Routing code 12 Emulator program (under os) 

Routing code 13 Available for customer usage 

Routing code 14 Available for customer usage 

Routing code 15 Available for customer usage 

Routing code 16 Reserved 



Byte z Reserved 

Byte 3 Reserved 

The ucMDESCD field contains the descriptor codes. A bit setting 
of "1" indicates that the wto or wtor was assigned that particular 
descriptor code. Bit assignments and their meanings are: 



Bit Assignment 

Byte 
Bit Descriptor code 1 



Meaning 



System failure 



Bit 1 
Bit 2 
Bit 3 
Bit 4 
Bit 5 
Bit 6 
Bit 7 
Byte 1 
Bit 



Descriptor code 2 
Descriptor code 3 
Descriptor code 4 
Descriptor code 5 
Descriptor code 6 
Descriptor code 7 
Descriptor code 8 

Descriptor code 9 



Descriptor codes 
10 through 16 



Immediate action required 

Eventual action required 

System status 

Immediate command response 

Job status 

Application program/processor 

Out-of-line message 

MLWTO message in response to a 
monitor or display command (exit 
routine not entered for mlwto) 
Reserved 

Reserved 
Reserved 



Byte 2 
Byte 3 

The exit routine is part of the communications task. Abnormal ter- 
mination of the exit routine causes the operating system to terminate 
abnormally (code of F03). 
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Messages that Don't Use 
Routing Codes 



The exit routine bypasses some messages. These are messages that have the 
MSGTYP operand in the wto or wtor macro instruction coded with the jobnames, 
STATUS, or Y parameter, and messages that are being returned to the requesting 
console; that is, a response to a display a command. Routing of these messages 
is on criteria other than the routing codes; therefore, the system bypasses the 
exit routine. 



Adding a WTO/WTOR Exit Routine to the Control Program 



A system generation option is available to enable you to include a resident, user- 
written exit routine in the communications task. 

The 0PTi0Ns=ExiT operand of the schedulr system generation macro instruc- 
tion controls the inclusion of the exit routine. A description of schedulr is found 
in the OS/VSI System Generation Reference pubHcation. 

Task supervision must be performed for the exit routine when the routine 
is requested at system generation. This supervision is performed every time a 
message is routed by its routing codes, even if the exit routine is not present. To 
maintain optimum throughput, the exit routine should not be specified at system 
generation unless it will be used. 



Inserting the WTO/WTOR 
Exit Routine 



To enter your exit routine into the control program before system generation, 
use the Hnkage editor to replace the dummy wto/wtor exit routine ieecvcte 
in SYsl.AOSB with your wto/wtor exit routine, ieecvxtt. 

To enter your exit routine into the control program after system generation, use 
the linkage editor to replace the dummy wto/wtor exit routine lEECVcrE in the 
SYsl.NUCLEUs with your wto/wtor exit routine. 



WTO/WTOR (Write to 
Operator/Write to Oper- 
ator with Reply) Macro 
Instructions 



The WTO and wtor macro instructions have two special operands, the msgtyp 
and MCSFLAG operands. These operands should be used only by the system 
programmer who is thoroughly familiar with the multiple console support ( mcs ) 
communications task, since improper use of these operands can impede the 
entire message routing scheme. These operands set flags to indicate that certain 
system functions must be performed, or that a certain type of information is 
being presented by the wto or wtor. 

Note: Multiple-line WTO messages are not passed to the user-written WTO exit routine. The 
WTOR macro instruction cannot be used to pass multiple-line messages. 

The MSGTYP and mcsflag operands may be specified on either the standard 
or list form of the wto and wtor macro instructions. The standard form of the 
WTO macro instruction is shown here. 



[symbol] 



WTO 



j 'message' i 

( ('text'[,line type] ),...f 



message 
text'[,line type] ), 

[,ROUTCDE = (number[,number] 

/ ( 

,MSGTYP = < JOBNAMES > 

STATUS \ 

ACTIVE )_ 
[,MCSFLAG = (name[,name] ,...)] 



.)] [,DESC = number) 
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message 

specifies that the message text is to be placed between the first and second 

apostrophes. 
( 'text' [,Une type] ) 

is used to write a multiple-Hne line message to the operator (no message is 

passed to the user- written wto exit routine for multiple-line message ) . 

ROUTCa)E= 

specifies the routing codes to be assigned to the message. 

DESC= 

specifies the descriptor codes to be assigned to the message. 

MSGTYP=JOBNAMES Or MSGTYP=STATUS 

specifies that the message is to be routed to the console which issued the 
DISPLAY jOBNAMES Or DISPLAY STATUS Command, respectively. When the 
message type is identified by the operating system, the message will be 
routed to only those consoles that had requested the information. Omission 
of the MSGTYP parameter causes the message to be routed as specified in the 
ROUTCDE parameter. 

[ ] indicates optional name or operand; select one from vertical stack within < [ 
MSGTYP=Y or MSGTYP=N 

specifies that two bytes are to be reserved in the wto or wtoe macro ex- 
pansion so that flags can be set to describe what msgtyp functions are de- 
sired. Y specifies that two bytes of zeros are to be included in the macro 
expansion at displacement wto -j- 4 -j- the total length of the message text, 
descriptor code, and routing code fields, n, or omission of the msgtyp para- 
meter, specifies that the two bytes are not needed, and that the message is 
to be routed as specified in the routcde parameter. If an invalid msgtyp 
value is encountered, a value of n is assumed, and a diagnostic message is 
produced (severity code of 8). 

When MSGTYP=Y, the issuer of the wto or wigr macro instruction that con- 
tains the MSGTYP information must set the appropriate message identifier bit 
in the msgtyp field of the macro expansion. Prior to executing the wto or 
WTOR SVC ( SVC 35 ) , he must also set byte of the mcsflag field in the macro 
expansion to a value of X'lO'. This value indicates that the msgtyp field 
is to be used for the message routing criteria. When the message type is 
identified by the system, the message will be routed to all consoles that had 
requested that particular type of information. Routing codes, if present, 
will be ignored. See Figure msg 2 for bit definitions for msgtyp^^y. 

MSGTYPrrACTIVE 

specifies that the multiple-line message is in response to a monitor a (mn a) 
command and should be routed to the console that issued the command. 



Bit 


Meaning 





DISPLAY JOBNAMES 


1 


DISPLAY STATUS 


2 


Reserved for future system use. Must be zeros. 


3 


QID field exists. 


4-15 


Reserved for future system use. Must be zeros. 



Figure MSG 2. Bit Definitions for MSGTYP=Y 
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Name 


Bit 


Meaning 







Routing and descriptor fields exist. 


REGO 


1 


Message is to be queued to the console whose source ID is passed 
in Register 0. 


RESP 


2 


The WTO is an immediate command response. 




3 


MSGTYP field exists. 


REPLY 


4 


The WTO macro instruction is a reply to a WTOR macro 
instruction. 


BRDCST 


5 


Message should be broadcast to all active consoles. 


HRDCPY 


6 


Message queued for hard copy only. 


QREGO 


7 


Message is to be queued unconditionally to the console whose 
source ID is passed in Register 0. 


NOTIME 


8 


Time is not appended to the message. 





9 


MLWTO indicator 





10-12 


Invalid entry. 


NOCPY 


13 


If the WTO or WTOR macro instruction is issued by a program in 
the supervisor state, the message is not queued for hard copy. 
Otherwise, this parameter is ignored. 




14-15 


Reserved for Graphics. 


Note: Invalid specifications are ignored and produce an appropriate error message. 1 



Figure MSG 3. MCSFLAG Parameters 



MCSFLAG 

specifies that the macro expansion should set bits in the mcsflag field as 
indicated by each name coded. Names and their corresponding bit settings 
are shown in Figure msg 3. 
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ROUTCDE, DEsc, and MSGTYP parameter combinations are shown in Figure 
MSG 4. Coding of any one of the four keyword parameters (routcde, desc, msgtyp, 
mcsflag) causes a new format wto or wtor to be generated. 



Parameter Coded 


Expansion Generates | 


No. 


ROUTCDE 


DESC 


MSGTYP 


MCSFLAG 


ROUTCDE 


DESC 


MSGTYP 


MCSFLAG 


1 
2 
3 

4 
5 


Specified 
Specified 
Specified 
Specified 
Specified 


Specified 
Specified 
Specified 
Specified 
Specified 


Y 

N 

JOBNAMES 

STATUS 

Omitted 


Optional 
Optional 
Optional 
Optional 
Optional 


Codes Specified 
Codes Specified 
Codes Specified 
Codes Specified 
Codes Specified 


Codes Specified 
Codes Specified 
Codes Specified 
Codes Specified 
Codes Specified 


Zeros 

Field Omitted 
X'8000' 
X'4000' 

Field Omitted 


As Specified ^ 
As Specified ^ 
As Specified § 
As Specified # 
As Specified # 


6 
7 
8 
9 
10 


Specified 
Specified 
Specified 
Specified 
Specified 


Omitted 
Omitted 
Omitted 
Omitted 
Omitted 


Y 

N 

JOBNAMES 

STATUS 

Omitted 


Optional 
Optional 
Optional 
Optional 
Optional 


Codes Specified 
Codes Specified 
Codes Specified 
Codes Specified 
Codes Specified 


Zeros 
Zeros 
Zeros 
Zeros 
Zeros 


Zeros 

Field Omitted 
X'8000' 
X'4000' 

Field Omitted 


As Specified # 
As Specified # 
As Specified # 
As Specified ^ 
As Specified ^ 


11 
12 
13 
14 
15 


Omitted 
Omitted 
Omitted 
Omitted 
Omitted 


Specified 
Specified 
Specified 
Specified 
Specified 


Y 

N 

JOBNAMES 

STATUS 

Omitted 


Omitted* 
Omitted* 
Omitted* 
Omitted* 
Omitted* 


Routing Code 2 
Routing Code 2 
Routing Code 2 
Routing Code 2 
Routing Code 2 


Codes Specified 
Codes Specified 
Codes Specified 
Codes Specified 
Codes Specified 


Zeros 

Field Omitted 
X'8000' 
X'4000' 

Field Omitted 


X'8000' 
X'8000' 
X'8000' 
X'8000' 
X'8000' 


16 
1? 
18 
19 
20 


Omitted 
Omitted 
Omitted 
Omitted 
Omitted 


Specified 
Specified 
Specified 
Specified 
Specified 


Y 

N 

JOBNAMES 

STATUS 

Omitted 


REGO/QREGO 
REGO/QREGO 
REGO/QREGO 
REGO/QREGO 
REGO/QREGO 


Zeros 
Zeros 
Zeros 
Zeros 
Zeros 


Codes Specified 
Codes Specified 
Ctxies Specified 
Codes Specified 
Codes Specified 


Zeros 

Field Omitted 
X'8000' 
X'4000' 

Field Omitted 


As Specified # 
As Specified # 
As Specified # 
As Specified # 
As Specified # 


21 
22 
23 
24 
25 


Omitted 
Omitted 
Omitted 
Omitted 
Omitted 


Omitted 
Omitted 
Omitted 
Omitted 
Omitted 


Y 

N 

JOBNAMES 

STATUS 

Omitted 


Omitted* 
Omitted* 
Omitted* 
Omitted* 
Omitted* 


Routing Code 2 
Routing Code 2 
Routing Code 2 
Routing Code 2 
Field Omitted 


Zeros 
Zeros 
Zeros 
Zeros 
Field Omitted 


Zeros 

Field Omitted 
X'8000' 
X'4000' 

Field Omitted 


X'8000' 
X'8000' 
X'8000' 
X'8000' 
Zeros 


26 
27 
28 
29 
30 


Omitted 
Omitted 
Omitted 
Omitted 
Omitted 


Omitted 
Omitted 
Omitted 
Omitted 
Omitted 


Y 

N 

JOBNAMES 

STATUS 

Omitted 


REGO/QREGO 
REGO/QREGO 
REGO/QREGO 
REGO/QREGO 
REGO/QREGO 


Zeros 
Zeros 
Zeros 
Zeros 
Zeros 


Zeros 
Zeros 
Zeros 
Zeros 
Zeros 


Zeros 

Field Omitted 
X'8000' 
X'4000' 

Field Omitted 


As Specified # 
As Specified # 
As Specified # 
As Specified # 
As Specified # 


* If an MCSFLAG other than REGO or QREGO is specified, the expansion generates the same fields except that the MCSFLAG 
field contains the MCSFLAG specified and the high-order bit set to 1 . 

# High order bit set to 1 to indicate a new format macro expansion (routing code and descriptor code fields exist). 



Figure MSG 4. ROUTCDE, DESC, and MSGTYP Combinations 



Message Routing Exit Routines MSG 9 



MSG 10 OS/VSl Planning and Use Guide 



The Must-Complete Function 



This section provides information concerning system 
routine use of the must-complete function. This func- 
tion is available to system routines operating in vsl as 
an extension of the enq/deq facilities. 



SecffOfi Outline 
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The Miist'Complete Funetion 



System routines (routines operating under a storage protection key of zero) 
often engage in updating and/or manipulation of system resources (system data 
sets, control blocks, queues, etc.) that contain information critical to continued 
operation of the system. These routines must complete their operations on the 
resource. Otherwise, the resource may be left in an incomplete state or contain 
erroneous information — either condition leads to unpredictable results. 

The must-complete function is provided in the enq service routine to ensure 
that a routine queued on a critical resource(s) can complete processing of the 
resource(s) without interruptions leading to termination. The eflFect of the must- 
complete function is to place other routines (tasks) in a wait state until the re- 
questing task — the task (routine) issuing a enq macro instruction with the set- 
must-complete (sMc) operand — has completed its operations on the resource. 
The requesting task releases the resource and terminates the must-complete con- 
dition through issuance of a deq macro instruction with the reset-must-complete 
(rmc) operand. 

Realize that, for the time it is in eflFect, the must-complete function serializes 
operations to some extent in your computing system. Therefore, its use should be 
minimized — use the function only in a routine that processes system data whose 
validity must be ensured. 

As an example, in multitask environments, the integrity of the volume table 
of contents (vtoc) must be preserved during an updating process so that all 
future users may have access to the latest, correct, version of the vtoc. Thus, 
in this case, you should enqueue on the vtoc and use the must-complete function 
( to suspend processing of other tasks ) when updating a vtoc. 

Just as the enq function serializes use of a resource requested by many dif- 
ferent tasks, the must-complete function serializes execution of tasks. 



Scope The must-complete function can be applied at two levels: 



the system level 



Only the requesting task, and system tasks included during system generation, 
are allowed to execute. All other tasks in the system are placed in a wait state. 



THE step level 



In a partition, only the requesting task is allowed to execute. All other tasks in 
the partition, including the initiator task, are placed in a wait state. 



CAUTION 

Use of the must-complete function at the system level should not be attempted 
until all alternatives have been exhausted. Except for extremely unusual 
conditions the system level of must-complete should never be used. 
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Requesting the Must- 
Complete Function 



You request the must-complete function by coding the set-must-complete (smc) 
operand in an enq macro instruction. The format is: 



name 


ENQ 


{ SYSTEM ) 
...,SMC= jsTEP \ 



You may specify system or step. The parameters system and step indicate 
the le\'el to which the must-complete function is to apply. The other operands 
of enq are described in the Supervisor Services and Macro Instructions publication. 

Because of the properties of the test and use parameters of the ret operand 
of the ENQ macro instruction, the smc operand should be used only if the ret 
operand is to use the parameters have or none (in the E-form of enq), or if the 
RET operand is not used at all. 

You may request the must-complete function only in routines operating under 
a protection key of zero. If the protect key is not zero, the task using the routine 
requesting "must complete" is abnormally ended. 



Operating Characteristics 



When the must-complete function is requested, the requesting task is marked 
as being in the must-complete mode and all asynchronous exits from the request- 
ing task are deferred. Other tasks in the system (except the allowed tasks at the 
system level) or tasks associated with the requesting task in a job step (step level) 
are placed in a wait state. Thus tasks external to the requesting task are pre- 
vented from initiating procedures that will cause termination of the requesting 
task. Other external events, such as a cancel command issued by an operator, 
or a job step timer expiration, are also prevented from terminating the requesting 
task. 

The must-complete mode of operation is not entered until the resource(s) 
queued upon are available. 

At the system or step level, the requesting task can cause its own abnormal 
termination. If the requesting task does come to an abnormal termination before 
a reset condition has been effected, the operating system is stopped at the point 
of error to permit investigation of the trouble. It is then necessary to restart the 
system with the initial-program -load (ipl) procedure. 



Programming Notes 



1. All data used by a routine that is to operate in the must-complete mode 
should be checked for validity to ensure against a program-check inter- 
ruption. 

2. A routine that is already in the must-complete mode should avoid calUng 
another routine which also operates in the must-complete mode. However, 
one level of nesting is permitted, when necessary, with the following 
cautions: 

a. A task may set the must complete mode for both the system and the step. 
If multiple settings are made for either the system or the step, only the 
first setting of each is effective — the others are treated as no operation. 

b. The same is true for reset-must-complete. The first rmc for the system 
will reset the status of the system, the first rmc for the step will reset 
the status of the step, and all others will be treated as no operation. 
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3. Interlock conditions that can arise with the use of the enq function are 
discussed in the Supervisor Services and Macro Instructions publication. 

Additionally, an interlock may occur if your routine issues an enq macro 
instruction while in the must-complete mode. The resource you want to 
queue on may already be queued on by a task placed in the wait state due 
to the must-complete request you have made. Since the resource cannot be 
released, all tasks wait. 

4. The macro instructions attach, link, load, and xctl should not be used, 
unless extreme care is taken, by a routine operating in the must complete 
mode. An interlock condition will result if a serially-reusable routine re- 
quested by one of these macro instructions has been requested by one 
of the tasks made non-dispatchable by the use of the smc operand or was 
requested by another task and has been only partially fetched. 

For example, suppose routine "b" in task B has requested and is using 
subroutine "c". Subsequently routine "a" in task A (of a higher priority 
than task B) receives control of the processing before routine "b" finishes 
with subroutine "c". If routine "a" issues an enq macro instruction with 
the SMC operand and puts task B (and, thus, routine "b") in a non- 
dispatchable condition, subroutine "c" remains assigned to routine "b". 
Now, if routine "a" issues a request ( via a link, load, etc. macro instruction ) 
for subroutine "c", an interlock will occur between tasks A and B: task A 
cannot continue since subroutine "c" is still assigned to task B, and task 
B cannot continue (and thus release subroutine "c") because task A in 
the must-complete mode has made task B nondispatchable. 

5. The time your routine is in the must-complete mode should be kept as 
short as possible— enter at the last moment and leave as soon as possible. One 
suggested way is to: 

a. ENQ (on desired resource(s)) 

{SYSTEM \ 
STEP J 

Item a gets the resource(s) without putting the routine into the must- 
complete mode. 

Later, when appropriate, issue the enq with the must-complete request 
(item b). Issue a deq macro instruction to terminate the must-complete 
moiae as soon as processing is nnisneu. 



Terminating the Must- 
Complete Function 



Terminate the must-complete function and release the resource queued upon 
by coding the reset-must-complete (rmc) operand in a deq macro instruction. 
The format is: 



name 


DEQ 


...,RMC=jSYSTEM/ 
/ STEP ) 



The parameter (system) or (step) must agree with the parameter specified 
in the smc operand of the corresponding enq macro instruction. 

Tasks placed in the wait state by the corresponding enq macro instruction 
are made dispatchable and asynchronous exits from the requesting task are 
enabled. 
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The PRESRES Volume Characteristics List 



This section describes the creation and use of a direct 
access volume characteristics list that is placed in the 
system parameter library under the member name 

PRESRES. 



Section Outline 



The PRESRES Volume Characteristics List PRE 1 
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Creating the List PRE 3 

PRESRES Entry Format PRE 3 
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Programming Considerations PRE 5 
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The PRESRES Volume Characteristics List 



You may use the pkeskes volume characteristics list to define the mount and 
allocation characteristics of direct access device volumes used by your installation. 
Use o£ the list enables you to predefine the mount characteristics (permanently 
resident, reserved) and allocation characteristics (storage, public, private) for 
any, or all, direct access device volumes used by your installation. The JCL 
Reference publication provides a full discussion of the volume characteristics 
and the operating system's response to the various designations. The information 
presented here describes the creation of the characteristics list, the format and 
content of entries in the list, and how the operating system uses the list. 



Creating the List 



You use the iebupdte utility program to place the list (under the member name 
PRESREs) in the system parameter library, sysI.paemlib. This utility is also used 
to maintain the list. 



PRESRES Entry Format 



Each PRESRES entry is an 80-byte record, consisting of a 6-byte volume serial 
number field, a 1-byte mount characteristic field, a 1-byte allocation characteristic 
field, a 4-byte device type field, a 1-byte mount-priority field, and an optional 



rmation field. Commas are used to delimit the fields, ex"*^-^ ^^- -or-^-*-:.'----! 



C/\.\^\^y\. Liic upiiwiiai 



info 

information field is always preceded by a blank. All character representation 

is EBCDIC. This format is shown below. 



Volume Serial 
Number 6 Bytes 



Device Type 
4 Bytes 



Optional 
Information 



•Blank-- 1 Byte 
•Mount Priority - 1 Byte 
'Allocation Characteristic ~ 1 Byte 



Mount Characteristic - 1 Byte 



The volume serial number consists of up to six characters, left justified. 
Mount characteristics are defined by: 

to denote permanently resident 

1 to denote reserved 

The default characteristic is "permanently resident" and is assigned if any 
character other than or 1 is present in the field. 

Allocation characteristics are defined by: 

to denote storage 

1 to denote public 

2 to denote private 

The default characteristic is "public" and is assigned if any character other 
than 0, 1, or 2 is present in the field. 
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The device type is defined by: 

A 4-digit number designating the type of direct access device on which 
the volume resides; for example, the ibm 2314 Direct Access Storage Facility 
is indicated by the notation 2314. Note that this field only indicates the 
basic device type for the associated volume. You must advise the operator 
if the device requires special features (such as track overflow) to process the 
data on the designated volume. 

The mount priority field is used to suppress mount messages at ipl time 
for a volume; the alphabetic character N should be inserted in this field 
to suppress the mount message. This field allows the user to list seldom 
used volumes in the presres li^t without having a mount message issued at 
each IPL. WTien these volumes are required, they may be mounted and attri- 
butes will be set from the peesres list entry. If the user does not wish to have 
the mount message suppressed, he may omit the mount priority field and the 
preceding comma. 

The optional information field contains: 

Any descriptive information about the volume that you may wish to enter. 
This information is not used by the system, but is available to you on a print- 
out of the list. If necessary, comments may start in the second byte after the 
mount priority field or if the mount priority field is omitted, in the second 
byte following the comma after the device type field. 

Embedded blanks are not permitted in the volume serial, mount, allocation, or 
device type fields. 



Operational Characteristics Upon receiving control from the nucleus initialization program (nip), the sched- 
uler compares the volume serial numbers in the presres characteristics list with 
those of currently mounted direct access volumes. Each equal comparison results 
in the assignment to the mounted volume of the characteristics noted in the 
PRESRES entry. (Fields in the unit control block for the device on which the 
volume is mounted are set to reflect the desired characteristics.) If the volume 
is: the ipl volume; the volume containing the data sets sysI.linklib, sysI.procleb, 
SYsl.SYSjOBQE; or 8. physically nondemountable volume, the mount characteristic 
(permanently resident) has already been assigned and only the allocation char- 
acteristic is set. 

A mounting list is issued for the volumes in the presres characteristics list that 
are not currently mounted ( except those for which mounting messages have been 
suppressed) and the operator is given the option of mounting none, some, or all 
of the volumes listed. The mount and allocation characteristics for the volumes 
mounted by the operator are set according to the presres Hst entry for the vol- 
ume. The operator selects the unit on which the volume is to be mounted. 

The applicable OS/VS Messages Library publication describes the operator 
messages and responses associated with the use of the presres volume character- 
istics list. 

After the scheduler has finished presres processing, reading of the job input 
stream begins and the presres list is not referred to again until the next ipl. 

Volume characteristics assigned by a presres list entry are inviolate. They 
cannot be altered by subsequent references to the volume in the input stream. 
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Nate: 

1. A PRESRES entry identifying a physically nondemountable volume will appear in the mount 
list issued to the operator if the volume ( device ) is offline or is not present in the system. 

2. Use of the presres list can only be suppressed by deleting the member from the para- 
meter library (sysI.parmlib). 

3. Only the first 102 volumes on the presres list can be placed on the mount Ust, 



Programming Considera- The only way to assign an allocation characteristic other than ' pubHc" to volumes 

*'0"s whose mount characteristic is "permanently resident" is through a presres char- 

acteristic list entry. 

Selection of the volumes for which presres entries are to be created should be 
done so that critical volumes are protected. Since the combination of mount and 
allocation characteristics assigned to a specific volume determine the types of 
data sets that can be placed on the volume and its usage, you can exercise effec- 
tive control over the volume through a presres list entry. 



The PRESRES Volume Characteristics List PRE 5 



PRE 6 OS/VSl Planning and Use Guide 



System Reader, Initiator, and Writer Cataloged Procedures 



In vsl, readers, initiators, and output writers are con- 
trolled by cataloged procedures. This section describes 
the reader, initiator, and writer cataloged procedures 
that are supplied by ibm, and tells how to write your 
own. 
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In vsl, system readers, initiators, and output writers are controlled by cataloged 
procedures. These procedures reside in the procedure library (sysI.proclib) and 
provide the parameters required for operation of the readers, initiators, and 
writers. 

IBM supplies cataloged procedures for readers, initiators, and for output writers. 
You can: 

• Use the iBM-supplied procedures. 

• Use the iBM-supplied procedures, and override given parameters. 

• Write and use your own cataloged procedures. 

• Write and use your own cataloged procedures, and override given parameters. 
The START command starts a reader, an initiator, or an output writer, and desig- 
nates the procedure to be used. If you use the start command to start a problem 
program, there will be no smf recording, or checkpoint/restart done for that job. 
You can override given parameters in the cataloged procedure by specifying the 
desired parameters in the start command. For a complete description of the 
START command, see the appropriate OS/VS Operator's Library publication. 

Some of your installation's parameters may differ consistently from those in the 
IBM-supplied procedure. If so, you may wish to use your own cataloged pro- 
cedure, rather than respecifying the parameters in every start command. You 
can use your own cataloged procedure by: 

1. Writing the procedure in the required format. 

2. Adding the procedure to the procedure library. 

3. Specifying the procedure name in the start command. 

To test your procedure by reference in another job but before adding it to the 
procedure library, format it as an in-stream procedure. See the OS/VS Job Control 
Language Reference publication for a description of in-stream procedures. (In- 
stream procedures can be used with any reader. ) 

If the parameter values in a cataloged reader, initiator, or writer procedure 
change frequently, use symbolic parameters in place of ordinary parameters. You 
may then assign values to the symbolic parameters in the start operator com- 
mand. For a description of the start operator command, see the appropriate 
OS/VS Operators Library publication. An illustration of the use of symbolic 
parameters is given in this section under Example of the Use of Symbolic Param- 
eters. 

Note: Symbolic parameters cannot be used for the program name on the exec statement in the 
reader, initiator, or writer procedure. 



Dato Set Integrity for Access during a job to a named data set depends on the disposition assigned it 

System Tasks in the dd statement. If a data set is named (DSNAME=anyname) and its status 

is either old or new ( Disp=status ) , the operating system gives exclusive control 
of that data set name to that job for the life of the job. 

If you start several concurrent system tasks ( such as several readers or several 
writers ) using the same cataloged procedure, this data set integrity feature would 
nevertheless permit only one reader, or one writer, to execute at a time. To avoid 
this undesirable serialization of access ( and hence, of the tasks ) for readers, the 
sysI.proclib data set is assigned a status of shr (in place of old). To avoid this 
for writers, the sysout data set name is exempted from the protection of the data 
set integrity feature (since shr cannot be assigned in place of new). 
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Reader Procedures 



Procedure Requirements 



The EXEC Statement 



lEEVMPCR is the cataloged procedure called when you issue mount commands. 
This procedure resides in sysI.procub. When not using an iBM-supplied cata- 
loged procedure library, you should add ieevmpcr to your own procedure library 
so that the mount commands can be properly executed. You can do this by using 
the lEBCOPY utiHty program. 

A cataloged procedure for a reader requires two job control statements: an exec 
statement and a dd statement. A second dd statement may be necessary if the pro- 
cedure library required is not sysI.proclib. See DD Statement for the Procedure 
Library in this section for specific details on when this statement is required. 
A third dd statement can be provided for reader abend. See DD Statement for 
Storage Dump in this section. The names and purposes of these statements are 
listed here: 

• An EXEC statement with the step name iefproc specifies the reader program. 

• A dd statement named iefrder provides the reader with a description of the 
input stream. 

• A DD statement named iefpdsi describes the procedure library (optional). 

• A dd statement named sysabend/sysudump requests a storage dump ( optional ) 
IBM supplies two reader procedures for vsl named rdr and rdrt. rdr is used 

with local unit record input devices and rdrt is used with local non-unit record 
input devices. The two procedures follow. Your installation must modify the 
reader procedure for use with remote devices ( see Procedure Requirements ) . 



Procedure: RDR 



/ / IEFPROC EXEC PGM=IEFVMA 
/ / PARM = 'bppttttsscccrlaaaaefh' 

//IEFRDER DD UNIT = 2540, LABEL = {,NL), VOLUME 

/ / DCB = (LRECL = 80, RECFM = F) 



SER = SYSIN, X 



Procedure: RDRT 



/ / IEFPROC EXEC PGM = lEFVMA, 

/ / PARM = 'bppttttsscccrlaaaaefh' 

//IEFRDER DD UNIT = 2400, LABEL = (,NL), VOLUME = SER = SYSIN, 

/ / DCB = (LRECL = 80, RECFM = F, BLKSIZE = 80) 



A description of the farm values is included under the heading The PARM 
Field in the EXEC Statement of the Reader later in this section. The iBM-sup- 
plied value of the farm field in the exec statement of both the rdr and rdrt pro- 
cedures is FARM='00600300005010E00011A'. 

When creating your own reader procedure, you must conform to the procedure 
format and the statement requirements. Use the iBM-supplied procedures as 
examples. The statement requirements are explained individually in the following 
paragraphs. 

When creating a reader procedure for use with remote unit record input de- 
vices, you must provide an exec statement as explained here, and a dd state- 
ment as explained in DD Statement for the Input Stream from a Remote Device 
in this section. 

The EXEC statement specifies the reader program and also passes a set of param- 
eters to it. The format of the exec statement is: 



/ / IEFPROC 

/ / 



EXEC PGM = lEFVMA, 

PARM = 'bppttttsscccrlaaaaefh' 



The step name must be iefproc, as shown. The parameter requirements are as 
follows : 



PRO 4 OS/VSl Planning and Use Guide 



The FARM Field in the 
EXEC Statement of the 
Reader 



PGM=IEFVMA 

specifies the reader program. The name o£ the program must be iefvma, as 
shown. 

FARM='bppttttsscccrlaaaaefh' 

is a set of parameters for the reader and interpreter. This parameter field 
must consist of 21 characters, but the last seven have default values and 
need not be specified. Their meanings are explained in the following text. 

b — character from through 7, which indicates what the addrspc= default 
will be, whether an account number is required or not, and whether a 
programmer name is required. The following chart shows the meaning 
of each possible character. 



PARM field value b 


Character 


ADDRSPC = default 


Acct. info, req'd 


Pgmr name req'd 





VI RT 


no 


no 


1 


VIRT 


no 


yes 


2 


VI RT 


yes 


no 


3 


VIRT 


yes 


yes 


4 


REAL 


no 


no 


5 


REAL 


no 


yes 


6 


REAL 


yes 


no 


7 


REAL 


yes 


yes 



pp — two numeric characters from 00 to 13 that indicate the default priority 
for jobs read from this input stream. When no priority is specified in the 
JOB statement, this default priority is assigned to the job. 

ttttss — six numeric characters that indicate the default for the maximum 
time ( in minutes and seconds ) that each job step may run. 

ccc — three numeric characters from 001 to 999 that indicate the default 
real size assigned to job steps read from this input stream when running 
virtual=real jobs. 

f — a numeric character from to 3 which specifies the disposition of com- 
mands from this input stream. The r parameter is used by the reader 
or interpreter whether or not the command is authorized to be entered 
into the input stream (see aaaa parameter). The reader and interpreter, 
iff is: 

— passes the command to the command scheduling routine to be exe- 

cuted. 

1 — displays the command ( by a ^VTO macro instruction ) , and passes it 

to the command scheduhng routine to be executed. 

2 — displays the command (by a wto macro instruction), asks the oper- 

ator whether the command should be executed (by a wtor macro 
instruction), and passes the command to the command scheduling 
routine if the operator replies in the affirmative. 

3 — ignores the command (treated as a no-operation). 

The WTO and wtor macro instructions issued by the reader and inter- 
preter are sent to the primary console in systems without the multiple 
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console support (mcs) option and to the mcs master console in systems 
with the MCS option. 

I -a. numeric character or 1 that specifies the bypass label processing op- 
tions. signifies that the blp parameter in the label field of a dd state- 
ment is to be ignored. The label parameter is processed as nl. 1 signifies 
that BLP is not to be ignored. The label parameter is processed as it 
appears. 

aaaa — four hexadecimal numbers. The first number must be an even number 
between and E. The next three numbers must be 0. These numbers 
indicate which operator command groups are to be executed if read from 
this input stream, (writer commands are not allowed in the input stream.) 
This parameter is valid only for systems with the multiple con- 
sole support option. In systems without the multiple console support 
option, this parameter is set to X'EOOO', permitting all commands except 
DEFINE and HALT to be entered into the input stream. In systems with the 
multiple console support option, default is to X'EOOO' when the param- 
eter is omitted. This processing applies to those commands that are 
passed to the interpreter; that is, those within some job stream, and those 
commands processed in the reader outside of any job stream. 

Figure pro 1 shows the operator commands that are affected by the 
aaaa parameter in an mcs environment. The commands are grouped by 
function. If the command is in a group authorized by the aaaa param- 
eter, it is processed. If the command is not authorized by the aaaa pa- 
rameter, it is ignored and an error message is sent to the master console. 

Informational commands (Group 0) are always valid when entered 
into the input stream. 



Command 
Group 


Function 


Commands 



1 

2 

3 
1,2,3 


Information 
System Control 

I/O Control 

Console Control 
Master Console 


BRDCST MONITOR SHOW 
CONTROL MSG STOPMN 
DISPLAY MSGRT 
LOG REPLY 

CANCEL MODE STOP 
CENOUT MODIFY SWAP 
DEFINE RELEASE SWITCH 
DUMP RESET USERID 
HALT SET WRITELOG 
HOLD START WRITER 

MOUNT UNLOAD VARY* 
SWAP 

VARY* 

All commands are valid, plus 
CONTROL M 
VARY MSTCONS 
VARY HARDCOPY 
VARY CONSOLE with AUTH- 


* Note: VARY (Group 2) is accepted only to vary non -console device online or offline. 

VARY (Group 3) provides only for console switching and console reconfiguration 
on secondary consoles. 



Figure PRO 1. Operator Command Groups 
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Bit settings for the aaaa, parameter are: 

Bit 

Settings 



Bytes 


(aa) 



1 

(aa) 



Bits 



1 

2 
3-7 



Meaning 

1 Group 1 commands executed 

1 Group 2 commands executed 

1 Group 3 commands executed 

00000 Reserved 



0-7 00000000 Reserved 



Example: If you wish to authorize commands from command groups 2 
and 3 to be executed vi^hen entered into the input stream, code the aaaa 
parameter '6000'. 

efh — MSGLEVEL value in absence of a value in the job statement. Unless 
there is a msglevel= entry in the job statement, job control statements 
and allocation/termination messages are recorded in the system output 
data set according to the value of the efh parameter. The values and 
their effects are: 

e — kind of job control statement recorded. 

— JOB statement only 

1 — Input statements, cataloged procedure statements, and symboHc 

parameter substitution values. 

2 — Input statements only. 

A blank defaults to a value of 0. 

f — kinds of allocation/termination messages recorded. 

— None, except in the case of an abend condition. ( In that event, 

all messages are recorded. ) 

1 — All 

A blank defaults to a value of 1. 

h — default message class. 



DD Stafement tor the 
Input Stream from a 
Local Device 



Your procedure for the reader must include a dd statement that describes the 
input stream. The format for this statement is: 



/ / lEFRDER DD UNIT = device, LABEL = (.type), X 

// VOLUME = SER = SYSIN, X 

/ / DCB = (list of attributes) [, DSNAME = name, DISP = OLD] 



This statement must be named iefrder, as shown. The iefrder statement can 
be overridden with a start command. The parameter requirements are as 
follows : 

UNiT=device 

specifies the device from which the input stream is read. This can be any 
device supported by the queued sequential access method (qsam). The 
device can be specified by its address, type, or group. 
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LABEL=(,type) 

describes the data set label ( needed only for tape data sets ) . If this param- 
eter is omitted, a standard label is assumed. 

Note: Label types AL and AUL (American National Standard Label types) should not 
be used. 



VOLUME=SER=SYSIISr 

specifies the volume containing the input stream. This parameter is required 
for magnetic tape or direct access volumes. The serial sysin is recommended 
for identification of this volume, but other serials can be used. 

Note: The volume serial numbers should not identify a volume that contains a data set 
written in ASCIL 



DCB=(list of attributes) 

specifies the characteristics of the input stream and the number of buffers 
acquired by jam (Job Entry Subsystem-oriented Access Method). The 
RECFM and LRECL subparamctcrs must be present and only fixed 80-byte input 
is valid. For unit record devices, the blksize subparameter may be modified 
to take advantage of command chaining available through jam. If you omit 
the BLKSIZE subparameter, jam acquires three buffers of the size indicated at 
sysgen time. (See the System Generation Reference manual for more details.) 
If the BLKSIZE subparameter is coded, the value specified on the dd state- 
ment overrides the amount of buffer space required by the reader as specified 
at sysgen time, blksize must be a multiple of lrecl and a blksize =800 would 
allow jam to read ten cards from the card reader with one ccw chain. Care 
should be taken to ensure that blksize (if specified) is not greater than that 
which was specified at sysgen. Otherwise, too little space may be available 
to allow readers and writers to operate at the level specified at sysgen time. 

The BUFNO parameter in the iefrder dd card is used to define the number 
of buffers that jam obtains. If this parameter is omitted, jam obtains three 
buffers of the specified or defaulted blksize. If coded, the only valid entry 
is 1, which would cause jam to obtain one buffer. One buffer can only be 
specified when blksize has been coded to indicate that command chaining is 
not being used; that is, blksize=80. Any other value is invalid and would 
result in three buffers being obtained. The specification of one buffer and no 
command chaining results in optimal use of storage since the jam input 
buffer wiU become part of the reader workarea. 

The DCB subparameters must be specified as required by qsam when read- 
ing from non-unit record input devices. When starting a reader to a non-unit 
record device using the iBM-supplied rdr procedure, blksize must be speci- 
fied with the START command; that is, 

S RDR.a,280„DCB=BLKSIZE=80 

When you use the rdrt procedure, it is not necessary to specify blksCze. 

DSNAME==name, DisP=disposition 

specifies the name and disposition of the input stream data set to be read. 
This keyword should be used only with direct access input stream. 

disp=old 

specifies that the input stream is an existing data set. 
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DD Stafemenf for the 
Input Stream from a 
Remote Device 



Your reader procedure for use with remote devices must include a dd statement 
that describes the input stream. The format for this statement is the same 
as the DD statement in the iBM-supplied reader procedure used with local unit 
record devices, except for a diflFerence in the unit specification and the addition 
of another parameter. These parameter requirements are: 



UNrr=BDn. 

specifies the remote unit record device from which the input stream is read. 
The device is specified in the form bdu, where n is the number representing 
the desired device of that type. 

TERM=:RT 

indicates that the input stream is read from a remote device. 

The UNIT specification can be overridden in the start command, but term=rt 
cannot be changed by the start command. 



DD Statement for the 
Procedure Library 



Your procedure for the reader can include a dd statement that defines the pro- 
cedure library. For maximum performance, the user should restrict himself to 
either using the iefpdsi dd statement, as indicated here, or omitting it. When used 
as illustrated or omitted, called procedures are not written to the sysI.syspool 
data set by the reader. They are instead read from the cataloged system proce- 
dure library by the interpreter. You can make use of private procedure libraries 
by replacing the standard iefpdsi dd statement with one describing the private 
procedure library or concatenating the private library(s) to the standard library 
by using the usual jcl conventions. However, if the reader procedure refers to a 
data set other than sysI.proclib, or supplies volume information, or concatenates 
procedure libraries, the reader will read the called procedures from their respec- 
tive libraries and write them to the sysI.syspool data set. 



//IEFPDSI DD DSNAME = SYS1.PR0CLIB, DISP = SHR 



This statement must be named iefpdsi, as shown. The parameter requirements 
are: 

DSNAME=SYS1 .PROCLIB 

identifies the procedure library. To concatenate other data sets with the 
system library, you must follow the iefpdsi dd statement with other unnamed 
DD statements, thus expanding the system procedure library. 

disp=shr 

specifies that the procedure library is an existing data set and can be shared 
with other tasks. 
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DD Statement for 
Storage Dump 



Your procedure for the reader can include a dd statement that allows you to 
receive a sysabend or sysxjdump storage dump if the reader reaches abend. If 
the SYsl.DUMP data set is properly defined and available to accept the dump, you 
will receive an svc dump. Otherwise, you will receive a sysabend or a sysudump, 
depending on which dd statement you include. If both sysabend and sysudump 
DD statements are included, the last one found is used. 



//SYSABEND DD SYSOUT=A 



//SYSUDUMP DD SYSOUT=A 



This statement can be named sysabend or sysudump, as shown. 

SYSOUT=A 

specifies the output class for the dump. 



Reader Procedure Used by 
Restart 



The procedure, named iefreint, used to process job control statements for a job 
being restarted, is a skeleton of the normal reader procedure. Its main functions 
are to define the restart reader program, named iefvrrc, and to make the pro- 
cedure library accessible to that program. The procedure is: 



Procedure: IEFREINT | 




lEFPROC 


EXEC 


PGM = IEFVRRC, RESTART READER PROGRAM X 








REGION = 50K, RESTART READER REGION X 








PARM = RESTART 




lEFRDER 


DD 


DUMMY 




lEFPDSI 


DD 


DSNAME = SYS1.PR0CLIB, DISP = SHR PROCEDURE 

LIBRARY 


/ / 


lEFDATA 


DD 


DUMMY 



Procedure Requirements 



When creating your own restart reader procedure, you must conform to the pro- 
cedure format and the statement requirements. Use the iBM-supplied procedures 
as examples. The statement requirements are explained individually in the fol- 
lowing paragraphs. 
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The EXEC Sfatemenf 



The EXEC statement specifies the restart reader program and passes a parameter 
to it. The format for the exec statement is: 



/ / lEFPROC EXEC PGM = lEFVRRC, REGION = nnnnnK, PARM = RESTART 



The step name must be iefproc, as shown. The parameter requirements are as 
follows : 

PGM=IEFVRRC 

specifies the restart reader program. The name of the program must be 
lEFVRRC, as shown. 

REGiON=nnnnnK (included for compatibility with vs2 and mvt. Not used by vsl.) 

FARM =RESTART 

must be coded as shown. 



DD Statement for the 
Input Stream 



Your procedure for the restart reader must include a dd statement that describes 
the input stream. The format for this statement is: 



/ / lEFRDER DD DUMMY 



This statement must be named iefrber, as shown. The parameter requirements 
are as follows: 

DUMMY 

must be coded as shown. System input is taken from the sysI.sysjobqe data 
set which is open already. 



DD Statement for the 
Procedure Library 



Your procedure for the restart reader must include a dd statement that defines the 
procedure library. This statement must follow the iefkder statement which de- 
scribes the input stream. The format for this statement is: 



/ / lEFPDSI DD DSNAME = SYS1.PR0CLIB, DISP = SHR 



This statement must be named iefpdsi, as shown. The parameter requirements 
are as follows: 

DSNAME^SYSl.PROCLIB 

identifies the procedure library. To concatenate other data sets with the 
system fibrary, you may follow the iefpdsi dd statement with other unnamed 
DD statements thus expanding the system procedure library. 

DISP=SHR 

specifies that the procedure library is an existing data set. 
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DD Statement for the 
CPP Data Set 



Your procedure for the restart reader must include a dd statement that defines the 
CPP (concurrent peripheral processing) data set. Since the data is already in the 
checkpoint data set, dummy serves as the operand. The format for this state- 
ment is: 



/ / lEFDATA DD DUMMY 



Initiator Procedures 



This statement must be named iefdata, as shown. The parameter requirement 
is as follows: 

DUMMY 

must be coded as shown. 



A cataloged procedure for an initiator requires two job control statements, an 
EXEC statement and a dd statement for the Scheduler Work Area Data Set 
(swADs). Additional dd statements may be optionally added so that specific con- 
trol volumes will be allocated to the initiator task. 

• An EXEC statement with the step name iefproc specifies the initiator program. 

• A dd statement with the step name iefrder provides the specifications for the 
swADS data set. 

• Optional dd statements specify control volumes to be allocated to the initiator 
task. 



IBM-Supph'ed Procedure 



The initiator procedure suppHed by ibm for vsl is named init. The init pro- 
cedure is: 



Procedure: INIT 



//IEFPROC EXEC PGM = lEFIIC, FARM = 'A, LIMIT = 13' 

//IEFRDER DD && SWADS, UNIT = 2314, SPACE = (176, (250) , , 

/ / CONTIG), DCB = (BLKSIZE = 176, LRECL = 176, 

/ / RECFM = F), DISP = (NEW, DELETE) 



Procedure Requirements 



When creating your own initiator procedures, you must conform to the procedure 
format and the statement requirements. The statement requirements are ex- 
plained individually in the following paragraphs. 
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7/ie EXEC Sfafemeni 



The EXEC statement specifies the initiator program and passes a set of parameters 
to it. The format of the exec statement is : 



/ / lEFPROC EXEC PGM = lEFIIC, FARM = 'x [(n)] [, x [(n )] . . . 



/ / 



2 '-^2^ 



[, LIMIT=K] ] 



The step name must be iefproc, as shown. The parameter requirements are: 

PGM=IEFIIC 

specifies the initiator program. The name of the program must be iefhc, as 
shown. 

PARM='x[(n)] [,Xj [(nj] . . . [,limit=k] ]' 
X — Job class (Letter A-O) 

(One to 15 job classes may be named.) (This parameter is ignored 

in vsl. ) 
n — (0-15), a force value priority at which all jobs from the preceding class 

will be run. (This parameter is ignored in vsl.) 
K — (0-15), the priority above which no job will be run by this initiator. 

(This parameter is ignored in vsl.) 

The preceding pabm values are allowed for compatibility with mvt and with 
vs2 but are not processed in vsl. 



DD Sfatemeni for the 
Scheduler Work Area Data 
Set (SWADS) 



The Scheduler Work Area Data Set (swads) facility is activated when the initi- 
ator is started. During the system's "start init" processing, the data set is allo- 
cated and initialized. Since swads is a temporary data set, care should be taken 
to avoid its destruction when temporary data sets are scratched during the use 
of lEHPROGM. The cataloged procedure for initiators contains a dd statement for 
the swADS. If an installation writes its own procedure for initiators, it must in- 
clude this DD statement as specified here: 



//lEFRDER DD 



DSNAME=&&SWADS,DISP= ( NEW,DELETE ) , 
UNIT= ,SPACE=( , ( ) , , CONTIG) 



All parameters are required exactly as shown, except that disp could be 
omitted since new,delete is the default and unit and space contain values deter- 
mined by the installation. These fields should be specified according to the fol- 
lowing: 

unit: Must be for one of the valid dasd types (2314, 2319, 2305-2, 3330, or 3333). 
It can be expressed as a unit type ( 2314 ) or as a group designation ( sysda ) , as 
long as the group does not include any non-supported device types, or as an 
actual channel and unit address. (When expressed as unit type, a 2319 is 
specified as 2314, and a 3333 is specified as 3330. ) 

Because all swads need not be on the same type device, an incompatibility 
is possible if the job uses the automatic step or checkpoint/restart features 
of vsl. If the SWADS of the initiator trying to restart the job has a smaller 
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track capacity than that of the swads used when the job was first run, re- 
start is not possible. In this case, the operator is informed and given the 
option of holding the job for restart by another initiator or of canceling 
the job. 

SPACE: The amount of space to request can be calculated according to a formula 
provided for the purpose. The formula is found in the VSl Storage Estimates 
pubHcation. This value, of course, depends on the size of the jobs that will 
be run in the installation. The subparameter contig is always needed. The 
actual request can be in terms of cyl, or trk, or 176-byte blocks. 

The iBM-suppHed initiator procedure contains values for unit and space. These 
values should, if necessary, be changed by the installation to reflect the needs of 
the specific system more accurately. You also have the ability to override these 
DD parameters in your start command for the initiator. This is useful if a par- 
ticular job to be run on a given day is known to be unusually large. It will be 
advantageous for the installation to override the space parameter when starting 
the initiator, rather than risk having the job canceled for lack of swads space. 
Generally, the overrides are useful when temporary changes are required. For 
permanent changes, the procedure should be modified so that the format of the 
START command is simplified. 



Dedicated Data Sets 



Dedicated data sets save the time taken repeatedly to allocate (and deallocate) 
space used only temporarily during a job step. A dedicated data set is allocated 
space when the initiator is started and belongs to the initiator. Every job step 
running under that initiator can use the dedicated data set as a temporary data 
set. If you use dedicated data sets for temporary data sets, the checkpoint/restart 
facility is internally suppressed. To dedicate any data set quickly to successive 
jobs or job steps, you add a dd statement to the initiator procedure. An initiator 
procedure (initd) for use of dedicated data sets with processor programs has 
been added to the system. To save repeated catalog searches, you may also dedi- 
cate system library data sets. 

The dedicated data sets feature has been implemented by adding code to the 
allocation routine that, before allocating space for a temporary data set, attempts 
to relate a request for a temporary data set with a dedicated data set. If the space 
required for the temporary data set fits within the dedicated data set, the dedi- 
cated data set space is used. If not, normal allocation takes place. The same 
criterion will be used with presently coded requests for temporary data sets, that 
is, if the space requested is within the range of the dedicated data set, it will 
be used. 



How fo Dedicate a Data Set 



You dedicate a data set by adding a dd statement ( for each data set to be dedi- 
cated) to the initiator procedure. The unit must be a dasd; the space may be for 
a sequential or partitioned data set. Each dd statement must be of the form: 



/ / ddname DD UNIT = unitparms, VOL = volparms, 

SPACE = (kind, (amount, increment, dirblks)), DISP = (NEW, 
DELETE) 
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ddname 

A user supplied ddname must be given to identify the dd statement. The 
ddname is used (in the form DSNAME=&ddname) in the dd statement of the 
problem program job step which is to make use of the dedicated data set. 

unitparms 

Parameters that describe the unit to be used for the dedicated data set. The 
unit must be a dasd. The aff= and defer unit parameters may not be used. 
The unit parameters specified here override those of the job step dd state- 
ment for which the dedicated data set is used. 

volparms 

Volmne parameters. 

A volume may be specified for each unit specified in the preceding unit 
parameter entry. The volume parameters specified here override those of the 
job step DD statement for which the dedicated data set is used. 

( kind, ( amount,increment,dirblks ) ) 

Type and size of space (in terms of cyl, trk, avgbl, or abstr) to be allocated 
to the data set. If ,dirblks is obmitted, the data set request implies sequential 
organization. If „dirblks is used, the data set request implies partitioned or- 
ganization. 

When a dedicated data set with partitioned organization reaches an eov 
condition, the initiator must be restarted. The dd statement in the problem 
program job step that is to use a dedicated data set must describe a problem 
program data set of the same organization as the dedicated one. Increments, 
once allocated, remain allocated until the initiator stops. 

NEW,DELETE 

These disposition parameters may either be coded explicitly or may take 
eflFect by default, that is by omitting the disp= entry. 

The effect of new is that the data set is freshly allocated from any avail- 
able space on the volume, each time a start initiator operator command is 
used or the system is restarted. 

The effect of delete is that the data set is not kept when the initiator is 
stopped and the space is available for reallocation to other jobs. 

DSNAME 

The allocation procedure for an initiator pre-alloeated data set is the same as 
for any temporary data set. This procedure is simplest with no dsname= entry 
in the dd statement. That results in a system assigned data set name of the 
form: 

SYSnumber.Rnumber.procname.RVnumber. 

You may also code DSNAME=&name, DSNAME=&&name, or DSNAME=name. 
These names will override those used in the job step dd statement for which 
the dedicated data set is used. 
DCB parameters: 

DCB parameters specified here have no effect. 



How io Get to Use a 
Dedicated Data Set 



If you want a dedicated data set to be used for a data set needed temporarily in 
a job step, define the temporary data set in a dd statement of the form: 



/ / ddname DD DSNAME = &ddname, 

/ / SPACE = (avgbl, (amount, increment, dirblks)), 

/ / UNIT = unitparms, DISP = (NEW, DELETE), DCB = dcbparms 
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&iddname 

name of the dd statement for the dedicated data set, preceded by an & sign. 

( avgbl, ( numbr, increment, dirblks ) ) 

Space request, in terms of average block length only, needed for this tempo- 
rary data set. 

An attempt to allocate the dedicated data set will be replaced by the nor- 
mal allocation procedure if one of the following conditions is encountered: 

• If the total space (primary and increments) requested here exceeds the 
total space (primary and increments) available to the dedicated data set. 

• If the use of ,dirblks (presence or absence) differs from that in the dd 
statement of the dedicated data set, (or if isam is specified). 

• If the space for ,dirblks requested here exceeds the space for ,dirblks 
specified in the dedicated data set. 

• If the space request is shown in other than average block length. 

unitparms 

Unit parameters 

Parameters that describe the unit to be used for the temporary data set, if 
the dedicated data set is not used. Here, the imit may be a magnetic tape 
unit, as well as a dasd. 

NEW,DELETE 

These disposition parameters must either be coded explicitly or may take 
effect through default. 

dcbparms 

DCB parameters required for your temporary data set. Unless specified, you 
may find that a previous user has left the dedicated data set with undesired 
DCB parameters. 



Procedure INITD 



Language processor programs (such as roRTRA.N compilers) make much use of 
temporary data sets. To permit ready use of the dedicated data set feature with 
IBM-supplied processor procedures, ibm supplies the initiator procedure initd, 
(It becomes part of the system by including it in the sysI.proclib at system 
generation time.) 

INITD is an initiator procedure that dedicates five utility data sets commonly 
used with iBM-suppfied processor procedures. To use the dedicated data set fa- 
cility with these procedures, start the initd initiator. 

Before including the initd procedure in your system, review the space alloca- 
tions, unit specifications, and ddnames used in the procedure against your re- 
quirements. If they are significantly different, you may wish to code your own. 

Existing procedures can be used under initd initiators. However, the job 
stream may be affected as described under Disposition of Temporary Data Sets. 
Procedures designed for the dedicated data set feature remain operative with- 
out the presence of the dedicated data set feature. In short, the procedure will 
run under any initiator regardless of whether that initiator has dedicated data 
sets. 



PRO 16 OS/VSl Planning and Use Guide 



The iNiTD procedure is as follows: 



Procedure: INITD 


//lEFPROC 


EXEC 


PGM = IEFIIC,PARM = 'A,LIMIT=13' 




// lEFRDER 


DD 


DSN = &&SWADS,UNIT=SYSDA, 


X 


// 




SPACE = (176,(250)„CONTIG),DISP = (NEW,DELETE) 




// SYSABEND 


DD 


SYSOUT = A,SPACE = (TRK,(1,10)) 




/ / SYSUT1 


DD 


DSNAME = &UT1,SPACE = (1700,(200,100)„CONTIG), 


X 


// 




UNIT=(SYSDA,SEP = lEFRDER) 




/ / SYSUT2 


DD 


DSNAME = &UT2,SPACE = (1700,(200,1 00)), 


X 


// 




UNIT= (SYSDA,SEP=SYSUT1 ) 




/ / SYSUT3 


DD 


DSNAME = &UT3,SPACE = (1700,(200,100)), 


X 


// 




UNIT= (SYSDA,SEP=SYSUT2) 




/ / SYSUT4 


DD 


DSNAME = &UT4,SPACE = (460,(700,100)), 


X 


// 




UNIT= (SYSDA,SEP=SYSUT3) 




/ / LOADSET 


DD 


DSNAME = &L0ADSET,UNIT=(SYSDA,SEP = SYSUT1), 


X 


// 




SPACE = (3600,(1 00,10)) 





INITD Procedure Statements 



Each of the statements shown in the preceding illustration is explained in detail 
in the following. In addition to describing the reason for or effect of the use of a 
parameter, the description distinguishes between those parameters that must be 
coded as shown and those that you may override or substitute for. 



The EXEC Statement 



The EXEC statement for the procedure is: 



// lEFPROC EXEC PGM = lEFIIC, PARM = 'A, LIMIT = 13' 



IEFPROC 

The step name. Must be coded as shown. 

EXEC 

The job control statement name. Must be coded as shown. Defines the begin- 
ning of a job step. 

PGM=IEFnC 

The program to be executed in this job step. iefsd060 is the name of the initi- 
ator program. Must be coded as shown. Whether dedicated data sets are used 
depends on the dd statements that follow, not on the name of the program. 

PARM=A,LIMrr=13' 

Parameter list for the initiator program. A is the class of jobs to be processed, 
LiMiT=13 is the dispatch priority limit for this initiator. These values are 
included for compatibility with mvt and vs2, but are ignored in vsl. 



DD Statement for the 
Scheduler Work Area Data 
Set (SWADS) 



The DD statement for the swads data set used with the initd procedure is the 
same as that described previously under the writeup of the init jwocedure. 
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DD Statemsnts for fbe 
Dedicated Ufility Data Sets 



Four DD statements in the initd procedure allocate space to four commonly used 
utility (or scratch) data sets. The statements are: 



//SYSUT1 


DD 


DSNAME = &UT1, SPACE = (1700, (200, 100),. CONTIG), 


// 




UNIT = SYSDA 


/ / SYSUT2 


DD 


DSNAME = &UT2, SPACE = (1700, (200, 100)), 


II 




UNIT = (SYSDA, SEP = SYSUT1) 


1 1 SYSUT3 


DD 


DSNAME = &UT3, SPACE = (1700, (200, 100)), 


II 




UNIT = (SYSDA, SEP = (SYSUT1, SYSUT2)) 


1 1 SYSUT4 


DD 


DSNAME = &UT4, SPACE = (460, (700, 100)), 


II 




UNIT = (SYSDA, SEP = (SYSUT1, SYSUT2, SYSUT3)) 



DSNAME 

The leading & sign marks the name as that of a temporary data set. 

SPACE= 

The first three data sets will be assigned space that can accommodate 200 
blocks of 1700 bytes. When that space is exhausted, additional space will be 
allocated for 100 blocks at a time. Additionally, for the first data set, sysxjtI, 
all the primary space is to be continguous when allocated. The fourth data set 
is to be allocated space for 700 blocks of 460 bytes initially. When exhausted, 
space is to be allocated for 100 blocks at a time. 



UNIT= 



Space is to be allocated from direct access storage devices. If possible, each 
data set is to be on a separate device from every other data set to avoid 
contention for the device. 



DD Statement for the Loadsei 
Data Set 



In the INITD procedure, the dedicated data set for the object module, the loadset 
data set, is defined as follows: 



//LOADSET DD DSNAME = &LOADSET, SPACE = (3600, (100, 10)), 
// UNIT = (SYSDA, SEP = SYSUT1) 



LOADSET 

DDName of the dedicated data set. 



DD 



Data definition statement 



DSNAME=&LOADSET 

A temporary dataset 

SPACE=( 3600, (100,10)) 

Space allocation commonly used in compilers. 

UNIT= 

Space is to be allocated on a dasd but not the same one as the sysutI data 
set. 



Use of Dedicated Data Sets 
by Processor Programs for 
Utility Data Sets 



Presently, processor programs show the temporary nature of the utility data sets 
by omitting a dsname=: entry. If these dd statements are revised with the addition 
of a DSNAME=&name entry, the system will attempt to use dedicated data sets of 
the initd program for job steps processed under that initiator. To illustrate the 
necessary change, let us look at a present dd statement and the change required. 
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The following is a dd statement from the cobeclg procedure for which a tempo- 
rary data set will be allocated : 



//SYSUT1 



DD UNIT - SYSDA, SPACE = (1024, (200, 65)) 



The temporary character of this data set is shown by the absence of a dsname= 
entry. To force consideration of the dedicated dataset, assuming that the step is 
running under the initd procedure, add a DSNAME=&name (or &&name) entry 
referring to the dedicated data set to be considered for use: 



/ / SYSUT1 

II 



DD 



UNIT = SYSDA, SPACE = (1024, (200, 65)), DSNAME 
&SYSUT1 



With the addition of the dedicated data set feature, the allocation program now 
first searches the dd statements in the initiator procedure for an already existing 
data set with a dd name like that following the & sign ( the symbolic name ) . If the 
allocation program finds such a data set, it next determines whether the organi- 
zation (sequential, partitioned) of the dedicated data set is the same as that of 
the temporary data set and whether the total space requirements (primary and 
increments ) of the temporary data set fall within the total space allocation of the 
dedicated data set. If there is no dedicated data set with the symbolic name, 
the organizations are not the same, or the temporary space does not fit within the 
dedicated space, the initiator will attempt normal allocation. It is for the latter 
event that unit parameters should be present. 



Processor Programs Library 
Data Sets as Dedicated 
Data Sets 



Processor programs library data sets, such as the coeol library, for example, may 
be referred to repeatedly in a batch of jobs. To save allocating the system data set 
in each job and step, the system data set can be dedicated in an initiator pro- 
cedure. Caution must be exercised when dedicating system libraries or other non- 
temporary data sets. The dd statement in the initiator procedure must have the 
disposition specified as old or shr and keep to prevent the deletion of the data set 
when the initiator is stopped. In the same manner the disposition on the job step 
DD statement referencing the dedicated library must also be old or shr and keep 
or PASS to allow the dedication to take place without a space comparison. The 
example data set references are as follows. 

The following is the dd statement in the cobecxg procedure that results in the 
allocation of the cobol library to the job step calling the procedure: 



//SYSLIB 



DD 



DSNAME = SYS1.C0BLIB, DISP = (SHR, KEEP) 
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The explicit data set reference (dsname=sys1.coblib) require a search of the 
catalog in each job step using the procedure. To save the repeated catalog search, 
move the dd statement to the initiator procedure and replace it in the cobeclg 
procedure with a dd statement in which the DSNAME=8aiame entry refers to the 
ddname of the dedicated data set. Allocation treats this as a dedication request, 
dedicated if so found. The new dd statement in the cobecjlg procedure, after 
adding the present one to the initiator procedure, is: 



//SYSLIB DD DSNAME = &SYSLIB, DISP = {SHR, KEEP) 



The result is one catalog search per initiator start instead of one catalog search 
every job step. However, keep in mind that this cobeclg procedure requires the 
initiator with the dedicated data set. Using this modified procedure with an un- 
modified initiator will result in failure to allocate. 



Disposition of Temporary 
Dedicated Data Sets 



Allocation/termination routines do not delete temporary dedicated data sets at 
the end of each job step, but, instead, keep them until the initiator stops; this 
occurs even if there is a specification of disp=(new,delete) or disp=(mod,delete) 
on the DD statement for the data set. Therefore, if you attempt to use such a data 
set a second time in the same job, it will contain data from the previous use. This 
can be a problem if you are using cataloged procedures and run the same pro- 
cedure twice within the same job. For example: assume that you use the proce- 
dure plIlflclg twice within the same job and it uses a dedicated data set with 
a disposition of (mod,pass) for the compile step and (old,delete) for the linkage 
edit step. When the procedure is entered for the second time, the object module 
produced by the second compile step will be placed in back of the object module 
produced by the first compile step. Since both object modules are assigned iden- 
tical names by the compiler, only the first will be linkage edited. 

You can avoid this problem by not using dedicated data sets for jobs that run 
the same cataloged procedure twice. Alternatively, you could submit each cata- 
loged procedure as separate jobs instead of submitting them as separate job steps 
within the same job. 

You can use the following chart to determine the disposition, by allocation/ 
termination, of temporary dedicated data sets. 



If you code 




DISP = 


Allocation/termination treats it as: 


NEW 


OLD 


OLD/SHR 


OLD 


MOD 


OLD 


.DELETE 


KEEP 


,PASS 


PASS 


.KEEP 


KEEP 
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Output Writer Procedures 



A cataloged procedure for output writers requires two job control statements: 
an EXEC statement and a dd statement. A second dd statement can be provided 
for writer abend. See DD Statement for Storage Dump in this section. 

• An EXEC statement with the step name iefproc specifies the output writer 
program. 

• A DD statement named iefrder defines the output data set. 

• A DD statement named sysabend/sysudump requests a storage dump (optional). 



System Output Writers 



IBM supplies two output writer procedures for vsl named wtr and wiiiT. wtr is 
used with local unit record output devices and wtrt is used with local non-unit 
record output devices. The two procedures follow. Your installation must modify 
the writer procedure for use with remote devices (see Procedure Requirements) . 







Procedure: WTR 




//IEFPROC 


EXEC 


IEFOSC01, 


X 






PARM = 'PA' 




//IEFRDER 


DD 


UNIT = 1403, VOLUME = (, , , 35), 


X 






DSNAME = SYSOUT, DISP = (NEW, KEEP), 


X 






DCB = (LRECL= 133), 


X 






RECFIVI= FM 





Procedure: WTRT 



//IEFPROC 


EXEC 


//IEFRDER 


DD 


II 




II 





PGM = IEFOSC01,PARM = 'PA' 

UNIT = 2400, VOLUME = (, , , 35), DSNAME = SYSOUT, 

DISP = (.KEEP), 

DCB = (RECFM = FM, LRECL = 133, BLKSIZE = 133) 



Procedure Requirements 



When creating your own output writer procedure, you must conform to the pro- 
cedure format and the statement requirements. Use the iBM-supplied procedure 
as an example. The statement requirements are explained individually in the 
following paragraphs. When creating a writer procedure for use with remote 
unit record output devices, you must provide an exec statement, as explained 
here, and a dd statement as explained in DD Statement for the Output Data Set 
for a Remote Device in this section. 



The EXEC Statement 



The exec statement specifies the output writer program and passes a set of pa- 
rameters to it. The format for the exec statement is: 



//IEFPROC EXEC PGM = IEFOSC01 , 

/ / PARM = 'cxxxxxxxx, seprname,#,TR,no,nnnn,y' 



The step name must be iefproc, as shown. The parameter requirements are 
as follows: 

PGM=IErOSC01 

specifies the output writer program. The name of the program must be 
lEFOscOl, as shown. 
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TARM=:'cxxxxxxxx,seprna7ne,4i:,TR,no,nnnn,y' 

is a set of parameters for the output writer program. The parameters are 
positional and a comma must be present to indicate the absence of a param- 
eter. The various parameters are explained: 

c — an alphabetic character, either P (for printer) or C (for punch) that 
specifies the type of control characters for the output of the writer. 

xxxxxxxx — from one to eight (no padding required) single-character class 
names for system output. These specify the type of output that the 
writer can process, and also establish the priority of the output classes, 
with the highest priority on the left. If class name parameters are in- 
cluded in the start command, they override this entire set of class names 
in the cataloged procedure. 

seprname — the name of the program (up to eight characters) that provides 
job separation in the output data set. You can specify the name iefosc06 
to use the output separator suppHed by ibm, or you can specify the 
name of your own program, which must reside in the Hnk Hbrary 
(sysI.linklib). This subparameter may be omitted, in which case no 
output separator is used. (Output separators are described in the Output 
Separation section.) 

# — the number (1, 2, or 3) of separator pages (printer) or cards (punch) 
produced by the iBM-suppHed output separators. This parameter is valid 
only if SEPRNAME is present and will default to three if omitted. This 
parameter is also passed to user- written output separator programs ( see 
Output Separation, a preceding section of this publication). 

TR — The TR parameter causes the writer to translate any unprintable char- 
acter to a blank. This parameter is vaHd only when the output device is 
a printer and the function is not performed if tr is omitted. 

no — the number of lines per page of printed output, with a maximum value 
of 254. This Hne count is only in effect when the data set does not 
contain control characters. This parameter is valid only when the output 
device is a printer and will default to 60 if omitted. 

nnnn — checkpoint interval. The number of pages (for printer) or logical 
records (for punch/tape devices) between checkpoints. This optional 
specification causes the writer to checkpoint sysout data sets, sysout 
data sets that are smaller than the indicated checkpoint interval are not 
checkpointed. If the number is not a multiple of 10, it is rounded down 
to the nearest multiple of 10. 

Output Device Type 

Printer — nnnnir:20 for a 1403 would cause a checkpoint in a data 
set approximately once a minute. 

Punch/Tape — nnnn=:300 for a 2540 would cause a checkpoint in a 
data set approximately once a minute. 

y — the number of end-of-job separator ( 1, 2, or 3 ) pages to be passed to the 
output separator program. The iBM-supplied separator prints that number 
of pages. This is valid only if seprname has been specified and output is 
destined for a printer device. Printer or punch destination is based on 
DD information, control character specification, and the writer parm field 
for non unit record devices. 
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DD Stafemenf tor the 
OUTPUT Data Set for a 
Local Device 



Youjf procedure for the output writer must include a dd statement that defines the 
output data set. The format for this statement is: 



//lEFRDER 


DD 


UNIT = device, LABEL = {,type), 


X 






VOLUME = (,,,voicount). 


X 






DSNAME = anyname, DISP = (NEW, KEEP), 


X 






DCB = (list of attributes). 


X 






UCS = (code [ , fold] [ , VERIFY] ), 


X 


II 




S ,ALIGN ) , 
FCB = (image-id ^ VERIFY ) ' 





This statement must be named iefrder, as shown. The parameter requirements 
are as follows: 

UNiT=<iet3ice 

specifies the printer, magnetic tape, or card punch device on which the out- 
put data set will be written. The devices that can be used are: 1403, 1442, 
1443, 2400, 2400-1, 2400-2, 2400-3, 2400-4, 2520, 2540, 3211, or 3525 with 
read feature. 

iASEL={,type) 

describes the data set label (needed only for tape data sets). If this param- 
eter is omitted, a standard label is assumed. 

VOLUMES ( ,„volcount ) 

limits the number of tape volumes that can be used by this writer during its 
entire operation (from the time it is started to the time it is stopped). This 
parameter is not required for printer or card punch devices. 

i>SNAME=anyname 

specifies a name for the output data set (tape only), so that it can be re- 
ferred to by subsequent job steps. This name is also necessary for specifica- 
tion of the KEEP subparameter in the disp field. 

DISP= ( NEW,KEEP ) 

specifies the keep subparameter to prevent deletion of the output data set 
(tape only) at the conclusion of the job step. 

T>CB=(list of attributes) 

specifies the characteristics of the output stream and the number of buflFers 
acquired by jam. The recfm and lrecl subparameters must be present in 
your procedure. For unit record devices, the blksize subparameter may be 
modified to take advantage of command chaining available through jam. 
If you omit the blksize subparameter, jam will acquire three buflFers of the 
size indicated at system generation time (see the VSl SYSGEN manual for 
more details). If the blksize subparameter is coded, the value specified on 
the DD statement overrides the amount of bufiFer space required by the writer 
as specified at sysgen time, blksize must be a multiple of lrecl, and a 
BLKSIZE- 798 would allow jam to accumulate six 133-byte print records be- 
fore initiating the i/o to the output device. Care should be taken to ensure 
that BLKSIZE, if specified, is not greater than that specified at sysgen. Other- 
wise, not enough space may be available to allow readers and writers to 
operate at the level specified at sysgen. 

The BUFNO parameter in the iefrder dd card is used to define the number 
of buflFers that jam obtains. If this parameter is omitted, jam will obtain 
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three buffers of the specified or defaulted blksize. If coded, the only valid 
entry is 1, which causes jam to obtain one buffer. One buffer can only be 
specified when blkseze has been coded to indicate that command chaining is 
not being used. Any other value is invalid and would result in three buffers 
being obtained. The specification of one buffer with no command chaining 
results in optimal use of storage since the jam output buffer will become part 
or the writer workarea. 

The DCB subparameter must be specified as required by qsam when writing 
to non-unit record output devices. W^en starting a writer to a non-unit 
record device using the iBM-supplied wtr procedure, blksize must be 
specified with the start command, that is, 

S WTR.W,280, , DCB=BLKSIZE=133 

When you use the wtrt procedure, it is not necessary to specify blkseoe. 

ucs=( code [jFold] [, verify] ) 

specifies the code for a universal character set (ucs) image that will be 
loaded into the ucs buffer, fold causes bits zero and one to be ignored when 
comparing characters between the ucs buffer and the print line buffer. This 
option allows lowercase character codes to be printed in uppercase by an 
uppercase chain/train, verify causes the ucs image specified to be output 
for the printer. The ucs parameter is optional and is valid only when the 
output device is a 3211 printer or a 1403 printer. 



FCB=( 



image-id ' ) 

|_ ,VERIFY J 



causes a forms control buffer (fcb) image with the specified image-id to be 
loaded into the fcb. One of two optional parameters, align or verify, can 
be coded, align and verify each allow the operator to align forms, verify 
also causes the fcb image to be output for the printer. The fcb parameter is 
optional and is vaHd only when the output device is a 3211 printer. 



DD Siatement for 
Storage Dump 



Your procedure for the writer can include a dd statement that allows you to 
receive a sysabend or sysudump storage dump if the writer reaches abend. 
If the SYsl.DUMP data set is properly defined and available to accept the 
dump, you will receive an svc dump. Otherwise, you will receive either a 
sysabend or a sysudump, depending on which dd statement you include. 



//SYSABEND DD SYSOUT=A 



//SYSUDUMP DD SYSOUT=A 



This statement can be named sysabend or sysudump, as shown. If both dd state- 
ments are included, the last one found is used. 

sysout=:a 

specifies the output class for the dump. 
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DD Statement for the 
OUTPUT Data Set for 
a Remote Device 



Your writer procedure for use with remote devices must include a dd statement 
that describes the output data set. The format for this statement is the same as 
the DD statement in the iBM-suppHed writer procedure used with local unit record 
devices except for a difference in the unit specification and the addition of 
another parameter. These parameter requirements are: 

vNnz=aan 
specifies the remote unit record device used to handle the output. 

aa — either pr (for printer) or pu (for punch) designates the device type. 

n — a numeric character that represents the desired device of that type. 

TERM=RT 

indicates that the output is going to a remote device. 



Direct SYSOUT Writer 
Procedures 



The direct sysout writer is an option in vsl that causes program output to be 
written directly from the problem program synchronously, with the exception of 
system messages, with execution of the problem program. There are two ibm- 
supplied direct system output writer procedures; dso and dsojs. The difference 
in the two procedures is that dsojs provides that output separators are written 
prior to the problem program output. A user-supplied procedure can be invoked, 
but it must execute the iBM-supplied direct system output writer. Both ibm- 
supplied procedures require two job control statements; an exec statement and 
a DD statement. 

• The EXEC statement is named iefproc, 

• The DD statem.ent is nam.ed iefrder and describes the ultimate output data set. 

The procedures supplied by ibm follow. If you wish to create your own pro- 
cedure, follow their formats. 



Procedure: DSO 



//IEFPROC EXEC PGM = lEFDSO, REGION = 8K, PARM = (PA, , , A) 
//IEFRDER DD UNIT = 2400, DSN = SYSOUT, DISP = (NEW, KEEP), 

/ / LABEL = (, SL), VOL = (, , , 05), DCB = (BUFNO = 3) 



Procedure: DSOJS 



//IEFPROC EXEC PGM = lEFDSO, REGION = 8K, PARM = (PA, IEFOSC06,3,A) . 
//IEFRDER DD UNIT = 2400, DSN = SYSOUT, DISP = (NEW, KEEP), X 

/ / LABEL = (,SL), VOL = (, , , 05), DCB = (BUFNO = 3) 
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The EXEC Sfatemenf 



The EXEC statement specifies the direct sysout writer. It is also used to give the 
writer program operating information. 



//lEFPROC EXEC PGM = lEFDSO, REGION = 8K, PARM = (ex, seprname, 
/ / nosep, jjj) 



iefproc 

Name of the exec statement. It is required as shown. 

iefdso 

Name of the writer program. 

region=8k 

Space required by iefdso to start. This parameter is included for compati- 
bility with MVT and vs2. It is not used by vsl. 

PARM= 

Information for the iefdso program. 

c — A letter, P for printer, or C for card punch, that describes the ultimate 
hard-copy medium. Must be given. 

X — The SYSOUT class to be processed. If stated here, and in the stabt com- 
mand, the latter rules. If not stated here, it must be given in the start 
command. 
,seprname 

Output separation program name. This may be omitted, but a comma must 

be written if other items follow. 

iErosc06 — Name of the iBM-supplied separator program. 
,nosep 

Number of output separators. This may be omitted if seprname is included, 

but a comma must be written if other items follow. The default value is 

three. 



,/// 



Job classes to be processed. From one to fifteen letters (A-O) showiug the 
job classes to be processed. If any job classes are named in the start com- 
mand, they overrule all stated here. If none are named here, the job classes 
are those assigned to the partition for which this writer is started. 



The DD Statement 



This DD statement describes the kind of volume to be used and the format of the 
data set. 



//lEFRDER DD UNIT = name, DSN = anyname, DISP = (NEW, KEEP), 
/ / LABEL = (, SL), VOL = (, , , volcount, DCB = (list) 



iefrder 

Name of the dd statement. Required as shown for iefdso. 



name 



Any form of unit identification may be used, such as OOE, 2400, or tape. 
Multiple parallel units (unit=2400,2) cannot be used. 
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Cataloging the Procedure 



DSN=anyname 

Name of a non-temporary data set. A name must be given. If stated here and 
in the start command also, the latter rules. The name is used in the dis- 
position messages at step termination, and must be used to identify the data 
set if it is to be printed later from tape. 

DISP= ( NEW,KEEP ) 

Required disposition. 

label=(,sl) 

If Dso is being used to write to magnetic tape, standard label tapes are re- 
quired. The label description may be stated explicitly or may be omitted, 
in which case sl is assumed. 

,„volcount 

1-225. The maximum number of volumes a data set to be processed by this 
writer will have. This determines the amount of job queue space allocated 
to each sysout data set processed by this writer. After the first five volumes, 
each subsequent 15 require another job queue record. If omitted, one is as- 
sumed. If stated here and also in the start command, the latter rules. This 
value cannot be given in the dd statement of a job to be processed. 



list 



The following dcb parameters gain control only if they are not also given in 
the SYSOUT DD statement or in the dcb macro instruction (that is, default 
values can be stated in this procedure ) : 

BFALN, BFTEK, BUFL, BUFNO, BLKSIZE, LRECL, RECFM, NCP, fflARCHY, UCS. 

The fouowing dcb parameters, if stated here, override all except those given 
in a START command: 

code, den, mode, optcd, prtsp, stack, trtch. 



Use the iebupdte utility program to add your reader, initiator, or writer proce- 
dures to the cataloged procedure library (sysI.proclib). Use of this program is 
fully explained in the OS/VS Utilities publication. 

The following example shows the control statements needed to add a reader 
procedure and an output writer procedure to the procedure library. For this ex- 
ample, the reader procedure is named rdproc4, and the output writer procedure 
is named wtproc2. 

The EXEC statement in this example specifies the iebupdte program. The 
parm=new parameter indicates that aU input to the utility program is contained 
in the data set defined by the sysin statement. 

The ADD control statement furnishes the name of the member to be added to 
the procedure library. The three numbers following the member name indicate: 

• The level of modification (00 indicates first run). 

• The source of the modification (0 indicates user-supplied). 

• The printed output desired (all indicates print entire updated member and 
control statements). 
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The NUMBER statement specifies the sequence numbers for records within the 
new member. With this statement, the number 00000010 is assigned to the first 
record of the new procedure, and subsequent records are incremented by 
00000010. 



//NEWPROCS 


JOB 


09#770,D.P.BROWN 




// 


EXEC 


PGM = lEBUPDTE, PARM = NEW 




//SYSPRINT 


DD 


SYSOUT = A 




/ / SYSUT2 


DD 


DSNAME = SYS1 .PROCLIB, DISP = OLD 




//SYSIN 


DD 


DATA 




./ 


ADD 


RDPR0C4, LEVEL = 00, SOURCE = 0, LIST = ALL 




./ 


NUMBER 


NEW1 = lOJNCR = 10 




//lEFPROC 


EXEC 


PGM = IEFVMA, 


X 


// 




PARM = '00101005010E00001 A' 




//lEFRDER 


DD 


UNIT = 2400-2, LABEL = (, NL), 


X 


// 




VOLUME = SER = SYSIN, 


X 


// 




DCB = (BLKSIZE = 80, LRECL = 80, BUFL = 80, 


X 


// 




BUFNO = 1, RECFM = F, TRTCH = C, DEN = 0) 




//lEFPDSI 


DD 


DSNAME = SYS1 .PROCLIB, DISP = SHR 




./ 


ADD 


WTPR0C2, LEVEL = 00, SOURCE = 0, LIST = ALL 




./ 


NUMBER 


NEW1 = 10, INCR = 10 




// lEFPROC 


EXEC 


PGM = IEFOSC01, 


X 


II 




PARM = 'PAC 




// lEFRDER 


DD 


UNIT = 2400-2, LABEL = (,NL),VOLUME = (,„40), 


X 


II 




DSNAME = SYSOUT, DISP = (NEW, KEEP), 


X 


II 




DCB = (BLKSIZE = 133, LRECL = 133, RECFM = F, 


X 


II 
/* 




TRTCH = C) 





Example of the Use of Symbolic Parameters In Cataloged Reader, 
Writer, and Initiator Procedures 



Symbolic parameters in a cataloged procedure that is started by the start 
operator command may be assigned values in the start command that starts the 
procedure. In this manner, any parameter in the exex: or in any dd statement 
may be assigned a value at the time the procedure is started. 

A cataloged procedure that uses symbolic parameters may also have a proc 
statement that shows the default values for the symbohc parameters. Keywords 
that may be used in a job, exec, or dd statement cannot be used as symbolic 
parameters. ( For example, you cannot say that disp is equal to fitREGiON. ) How- 
ever, subparameter keywords of the dd statement can be used as symbolic param- 
eters. (For example,, you may code bufno=&bufno. ) 
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The following example shows a reader procedure that contains symbolic 
parameters. 



// RDPR5 


PROC 


STIME = 030, MCS = EOOO, MSGL = 01, 


II 




PDSI = 'SYS.1.PR0CLIB' 


//lEFPROC 


EXEC 


PGM = lEFVMA 


II 




PARM = '001&STIME.05010&MCS&MSGL.A' 


//lEFRDER 


DD 


UNIT = 2400, LABEL = (,NL), VOLUME =SER=SYSIN, 


II 




DCB = (BLKSIZE = 80, LRECL = 80, BUFL = 80, 


II 




BUFN0 = 1,RECFM = F) 


//lEFPDSI 


DD 


DSNAME = &PDSI, DISP = SHR 



Ihe PROC Statemenf 



In the preceding illustration the proc statement assigns default values to the 
symbolic parameters &stime,&mcs,&msgl,8jpdsi. 



The START Command 



These same symbolic parameters are assigned values with the following start 
command: 



START RDPR5, STIME -035, MCS = EOOO, MSGL= 11, PDSI = 'SYS1. USER' 



Blocking the Procedure Library 



You may, in some cases, improve the use of direct access space and gain per- 
formance advantages by blocking the procedure Hbrary. It may be blocked at 
system generation or subsequently by using the operating system utiHties. Block 
size must be a multiple of 80. 

The following example shows the control statements needed to block the pro- 
cedure library using the iebcopy and iehprogm utiHty programs. Step CI of job 
BLOCK copies the procedure Hbrary and blocks it to 400. It deletes the old copy 
and catalogs the new copy under the name of libcopy. Step Rl renames the pro- 
cedure library to sysI.proclib and catalogs it under that name. 



Reader, Initiator, and Writer Cataloged Procedures PRO 29 



//BLOCK 


JOB 


ACCT, D82,MSG LEVEL = 1 




//CI 


EXEC 


PGM=IEBCOPY 




/ / SYSUT1 


DD 


DSNAME = SYS1 . PROCLIB, UNIT = 2314, DISP = (OLD, 




II 




DELETE, KEEP) 




1 1 SYSUT2 


DD 


DSNAME = LIBCOPY, UNIT = 2314, VOLUME = 


X 


II 




SER = 111111, 


X 


II 




DISP = (NEW, CATLG, DELETE), DCB = (RECFM = FB, 


X 


II 




LRECL = 80, 


X 


II 




BLKSIZE = 400), SPACE = (TRK, (50, 1, 10)) 




//SYSPRINT 


DD 


SYSOUT = A 




//SYSIN 

/* 

//R1 


DD 


DUMMY 




EXEC 


PGM = IEHPROGM 




//DD1 


DD 


UNIT = 2314, VOLUME =SER = 1 1 1 1 1 1, DISP = OLD 




//SYSPRINT 


DD 


SYSOUT = A 




//SYSIN 


DD 


* 




RENAME 


DSNAME = LIBCOPY,VOL=2314= 111111 ,NEWNAME = 






SYS1. 


PROCLIB 




CATLG 

/* 


DSNAME = SYS1.PROCLIB,VOL = 2314=111111 
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Resident Routines Options 



The resident routines options are the bldl feature, the 
resident reenterable modules feature, and the rsvc and 
RERP features. These features permit preloading into 
storage routines (or at least their addresses) that other- 
wise would be repeatedly loaded each time tlie rou- 
tines are requested. The purpose of these options is to 
improve performance by reducing or eliminating the 
access time required to obtain the routines with which 
these options are concerned. 

The link hst feature, also described in this section, 
permits references to the link library to be extended 
to other data sets. 



SecffOfi Oufline 



Resident Routines Options RRO 1 

BLDL and Resident Routines Feature RRO 3 

The Resident BLDL Table Option RRO 3 
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The Resident Access Method Modules Option .... RRO 6 
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BLDL and Resident Routines Features 



The BLDL, reenterable modules, rsvc and keep options, when included in your 
system, enable you to make resident in the pageable supervisor area: 

1. All, or a selection of, link or svc library directory entries. 

2. A selected group of access method routines. 

3. A selected group of type 3 and 4 svc routines. 

4. A selected group of error recovery procedures. 

5. Reenterable routines from the link library, and svc library. 

Placement occurs during the system initialization process. The routines or 
svc/link library entries may be pageable or fixed (rerp routines are always Qxed) 
and reside in the pageable supervisor. Additionally, the fixed items are long-term 
fixed in the high end of real storage. That is, the fixed items occupy space in 
both virtual and real storage but are not subject to paging. 

In the following discussions, the term resident is often used. As applied to the 
resident routines option, resident means existing in the pageable supervisor area 
and may be pageable or fixed, depending on the option selected (ram or ramf, 

RSVC or RSVCF, BLDL Or BLDLF ) . 

These options are included in the system when it is generated. The System 
Generation Reference publication describes the procedure. 
You specify: 

1. the Hnk library (sysI.linklib) and svc library (sysI.svclib) routines and 
directory entries 

2. the access method routines 

3. the type 3 and 4 svc routines 

4. the error recovery procedures to be made resident through lists of linkage 
library, access method, svc routine and error recovery procedure load module 
names placed in the parameter library (sysI.parmlib). 

Standard lists (as shown in Figure rro 1) exist for every option. The standard 
Hst (so called because its member name in the parameter library is predefined) 
is automatically referred to during the initialization process when the option is 
either selected or defaulted to during sysgen and is neither canceled or modified 
in response to message ieaIOIa specify system and/or set parameters for 
release xx.yy.sssss. All standard lists, except ieabldOO, are built at sysgen. 
ieablduu is copicu irom tue starter system, oome stanaaria aISlS contam module 
names and some lists are null. 

A portion of this section discusses the function of each option, the creation of 
the parameter library lists, and, fists the content of the resident access method 
modules and resident type 3 and 4 svc routines standard lists. The Message Li- 
brary publication describes the message (message number ieaIOIa) and replies 
associated with the options. 



The Resident BLDL Table Option 



System issued attach, link, load, or xctl macro instructions requesting load 
modules from partitioned data sets cause a search of the data set directory for 
the location of the requested module (the bldl table operation) and a fetch of 
the module. The resident bldl table option eliminates the directory search re- 
quired during execution of these macro instructions when a load module (whose 
directory entry is resident) is requested from the linkage or svc libraries. 

This option builds lists of directory entries for use by attach, link, load, or 
xctl macro instructions requesting linkage or svc Hbrary load modules. During 
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Option 

-^ 


Pageable 
BLDL 


Fixed 
BLDL 


Pageable 
RSVC 


Fixed 
RSVC 


Pageable 
RAM 


Fixed 
RAM 


Fixed 
RERP 


How to specify 
at SYSGEN 


Defaulted 


CTRLPROG 
OPTIONS = 
BLDL 


CTRLPROG 
RESIDNT = 
TRSVC 


CTRLPROG 
RESIDNT = 
TRSVC 


Defaulted 


Defaulted 


CTRLPROG 
RESIDNT = 
ERP 


Standard list 
associated with 
the option 


lEABLDOO 


lEABLDOO 


lEARSVOO 


IEARSV01 


lEAIGGOO 
IEAIGG02 


IEAIGG01 
IEAIGG03 


lEAIGEOO 


How to specify 
at IPL 


BLDL = 


BLDLF = 


RSVC = 


RSVCF = 


RAM = 


RAMF = 


RERP = 










iVIay be speci- 
fied at IPL 
whether oi- not 
specified at 
SYSGEN 


Yes 


Yes 


No 


No 


Yes 


Yes 


No 


Number of 
lists which may 
be specified 


2 


2 


1 


1 


4 


4 


1 


Names on the 
list 


SVC or link 
library rou- 
routines 


SVC or link 
library rou- 
routines 


Type 3 and 4 
SVC routines 


Type 3 and 4 
SVC routines 


Access method 
and re- 
enterable link 
library 
routines 


Access method 
and re- 
enterable link 
library 
routines 


Error recovery 

procedure 

routines 


Library of 
residence 


SYS1.SVCLIB 
SYS1.LINKLIB 


SYS1.SVCLIB 
SYS1.LINKLIB 


SYS1.SVCLIB 


SYS1.SVCLIB 


SYS1.SVCLIB 
SYS1.LINKLIB 


SYS1.SVCLIB 
SYS1.LINKLIB 


SYS1.SVCLIB 
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execution of the bldl operation in the macro instruction routines, the hbrary 
directory is searched only when the directory entry for the requested load 
module is not present in the resident bldl table. 

You hst, in a member of sysI.parmlib, the names of those linkage or svc library 
load modules whose directory entries are to be made resident. The member 
name for the standard list is ieabldOO. The load module names must be hsted 
in the same order as tliey appear in the directory; that is, they must be in 
ascending collating sequence. Creation of parameter library Hsts is discussed 
later in tliis section. The next part of this section provides guidehnes for choosing 
the content of the list. 

Ncftes: 

1. Directory entries in the resident table are not updated as a result of updating the load 
module in the library. The old version of the load module is used until an IPL opera- 
tion takes place and the new directory entry for the module is made resident. 

2. BLDL and BLDLF are mutually exclusive. By specifying either one during system 
initialization, the other is overridden. 



Selecting Entries for the 
Resident BLDL Table 



Any load module in the linkage or svc library may have its directory entry 
placed in the resident bldl table. Other items you should consider are: 

1. Table size (probably only a factor if bldlf is used). 
Linkage library — Each entry requires 40 bytes. 
svc library — Each entry requires 32 bytes. 

2. Frequency of use of the load module. 
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Table Size 



The BLDL table, when bldl is specified^ occupies pageable storage (virtual stor- 
age) and the table size is usually not a problem. The bldl table, when bldlf is 
specified, occupies real storage and each installation should carefully consider 
how much real storage it can afford to dedicate for this function. 



Frequency of Use 



Since fixed resident routines reduce the amount of real storage available for 
paging, your installation's workload should be carefully considered before select- 
ing the BLDLF option. The bldl option, on the other hand, will always be beneficial 
for any frequently-used load modules. 

For Link Library Lists: The scheduler, linkage editor, and language processor(s) 
are possible selections for link library lists. 

For SVC Library Lists: In general, use any module from the svc library you 
would consider for residence (for example, the ram option). You should not 
create lists for the following because they are not necessary: 

• Load 1 of type 3 and 4 svcs (that is, IGCOOxxx). 

• Modules selected for ram, rerp, rsvc, ramf, or rsvcf usage. 
Recommended modules should be chosen from access methods and erps. You 

should always avoid placing the following modules in the bldl list because they 
have internal bldl tables and internal directory entries: open, close, tclose, eov, 
FEOv, SCRATCH, ALLOCATE, lEHATLAS, SETPRT, STOW, machinc-check handler mod- 
ules. 

You can put the svc library list in sysI.parmlib using the member name 
lEABLDnn. This nn will be picked up when the operator specifies the system 
parameters with the response BLDL=xx,nn. 

The code to support the resident bldl table option is standard in vsl. 



List lEABLDOO 



The IBM supplied standard list ieabldOO is: 

SYSl.LINKLIB DEVMASKT,GO,HEWLOADR,IEEVRCTL,IEEVSTAR,IEFALRET, X 

IEFIRC,IEFIRET,IEFSDA66,IEFSD060,IEFSD065,IEFSD161, X 

IEFSD162,IEFSD263,IEFSD510,IEFV4221,IEFWCOOO,IEFWDOOO, X 

IEFW21SD,IEFW42SD,IEFX5000,IEWL,IEWLDRGO,IEWLOAD, X 
IEWLOADR,IEWSZOVR,LINKEDIT 



Resident Reenterable Modules Options 



These options make it possible to pre-load reenterable modules into storage. 
These two options (the resident access method modules option and the resident 
link library modules option) use similarly named load lists (ieaigg..) and share 
an operator reply (ram= and ramf=) at initialization time to refer to their 
separate lists. 

The system has standard resident access method lists (ieaiggOO and ieaiggOI) 
and standard resident link library module lists (ieaigg02 and ieaiggOS) which are 
used unless you have changed them or ask for the use of other lists in the 
operator reply to message ieaIOIa. 
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To use both access method modules and link Hbrary modules options, the 
operator reply is ram and/or RAMF=kk,ll,mm,nn. Each pair of letters represents 
a pair of alphanumeric characters (like 01) that identify a list of either access 
method or link library modules. 

These options place reenterable load modules in storage and create a resident 
list of the modules. A load, link, xctl, or attach macro instruction requesting 
any module first scans the resident list. If the module is listed, no fetch operation 
is required. 

You may list, in a member of sysI.parmlib, the load module names of modules 
to be made resident. Standard lists of most frequently used modules are supplied 
by IBM. The content of the standard iBM-supplied lists is tabulated at the end 
of this description. If you desire your modules to be put into the ibm standard 
lists ieaiggOO-03, you may use the sysgen linklib and svclib macros. 



The Resident Access 
Method Modules Option 



The storage space required for each access method module consists of the byte 
requirements of the module and its associated load request block (lrb). The 
Storage Estimates publication provides the byte requirements for access method 
modules eligible to be made resident. The code supporting the option is standard 
in vsl. 



Most access method modules placed in storage are "only loadable", attach, 
LINK, and XCTL macro instructions must not refer to such modules. 

You may alter the standard access method list (or create alternative Hsts) to 
include other access method modules. 



For example, if checkpoint/restart is used, the following access method rou- 
tines must be resident: 

• igg019c1, igg019c2, and igg019c3 if track overflow is used to write the data set. 

• iggOIQht (a page fix appendage) if virtual storage is specified for the task. 

When a composite console is used, an alternative list should include bsam 
modules for card readers and printers. 

If you specify either the 3330 or the 2305 i/o devices in your system, add the 
following modules to the standard ram list (ieaiggOO): 

IGG019C4, IGG019FN, IGG019FP, and IGG019EK 

IGG019C0 must also be resident and is on the standard RAM list. 

If you use the sam 'search direct' option, you are strongly advised to make 
iggOIQfn, igg019fp, and igg019c4 resident through the standard ram list. Per- 
formance is improved and required partition size is decreased if these modules 
are resident. 

To be eHgible for use with the resident access method option, access method 
load modules must be reenterable. 
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List iEAIGGOO 



The content of the iBM-suDDlied standard list ieaiggOO is: 



Module Name Access Method Function 

Channel end (appendage), search-direct 
Backward move — format F, FB, U records 
Backward locate — format F, FB, U records 
Magnetic tape forward space or backspace 
GET move with CNTRL — format V records (card 
reader ) 

PUT move, format F, FB, U records 
PUT locate, format V, VB records 
GET locate, format V, VB records 
PUT move, format V, VB. records 
GET move, format V, VB records 
NOTE/POINT tape 
GET move, format F, FB, U records 
PUT locate for dummy data set 
GET locate, format F, FB, U records 
Read length check, format V records ( appendage ) 
Channel end ( format U ) 
End-of-extent ( appendage-find new extent ) 
RPS, SIO, CE, and XE appendages 
SIO and page-fix (appendage) — RPS 
GET/PUT/PUTX JES compatibility interface 
processing 

GET synchronization routine 
NOTE/POINT disk 

READ/WRITE/CHECK JES compatibility interface 
processing 

PUT locate, format F, FB, U records 
PUT synchronization routine 

Verify GET/PUT/POINT requests by JES compati- 
bility interface modules 

Length check, format FB records ( appendage ) 
CHECK (all devices) 
Schedules I/O for tape, direct access 
READ/WRITE (all devices) 
End-of-extent check (data extent block) 
(appendage ) 

SIO and page-fix (appendage) 
Schedules I/O for direct access output 

SB=simple buffering 

SAM=common sequential access method routines 

If the system generation statements specify the use of both mcs and of an ibm 
2740 Communication Terminal as an operator's console, list ieaiggOO is extended 
by adding the following module names: 



IGG019FP 


SAM 




IGG019AN 


QSAM 


(SB) 


IGG019AM 


QSAM 


(SB) 


IGG019BE 


BSAM 




IGG019AG 


QSAM 


(SB) 


IGG019AK 


QSAM 


(SB) 


IGG019AJ 


QSAM 


(SB) 


IGG019AB 


QSAM 


(SB) 


IGG019AL 


QSAM 


(SB) 


IGG019AD 


QSAM 


(SB) 


IGG019BD 


BSAM 




IGG019AC 


QSAM 


(SB) 


IGG019AV 


QSAM 


(SB) 


IGG019AA 


QSAM 


(SB) 


IGG019CJ 


SAM 




IGG0I9C0 


SAM 




IGG0I9C4 


SAM 




IGG019EK 


SAM 




IGG019FN 


SAM 




IGG019DJ 


QSAM 


(SB) 


IGG019AQ 


QSAM 


(SB) 


IGG019BC 


BSAM 




IGG019DK 


BSAM 




IGG019AI 


QSAM 


(SB) 


IGG019AR 


QSAM 


(SB) 


IFGAAABA 


SAM 




IGG019CI 


SAM 




IGG019BB 


BSAM 




IGG019CC 


SAM 




IGG019BA 


BSAM 




IGG019CH 


SAM 




IGG019HT 


SAM 




IGG019CD 


SAM 





IGG019MA 
IGG019MB 
IGG019MO 
IGG019MR 



BTAM Read/write module 

BTAM Appendage 

BTAM 2740 module 

BTAM Online Test Control module 



If the system generation statements specify that the ibm 3211 Printer is to be 
included in the system, the following modules are added to the list: 

IGG019FR 
IGG019FS 
IGG019FT 

Modules specified with sysgen macro svclib virtual= , whose names begin 
with characters other than igc, igx, or ige are also put on list ieaiggOO. 



List IEAIGG01 



The IBM-supplied standard list ieaiggOI contains modules specified with the 
sysgen macro svclib residnt=, whose names begin with characters other than igc, 
igx, or IGE. If there are no module names for fist ieaiggOI, it is created as a null 
member (it exists on sysI.parmlib, but has no entries). 
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Resident Link Library 
Modules Option 



The storage space required for each link Hbrary module consists of the byte re- 
quirements of the module and its associated loaded program request block (lprb). 
The code supporting the option is standard in vsl. 

To utihze the option in your system: 

• Add a list or lists of names of reenterable modules to be preloaded, to the 
parameter library. Each module name must be followed by its alias names 
(separated by commas). 

• Have the operator specify your list or lists in his ram= or ramf= reply at 
iPL time. 

ISIote: Small (real storage) users should not use RAMF. This further reduces real storage 
space for paging. 

• As an alternative, you can have your modules put on the standard lists 
ieaigg02 and 03. A description of these lists follows. 



List iEAiGG02 



The IBM-supplied standard list ieaigg02 contains modules specified with the 
sysgen macro linkub virtu al=. If there are no module names for list ieaigg02, 
it is created as a null member (it exists on sysI.parmlib, but has no entries). 



List 1EAIGG03 



The IBM-supplied standard Hst ieaiggOS contains modules specified with the 
sysgen macro linklib resident^. If there are no module names for list ieaiggOS, 
it is created as a null member (it exists on sysI.parmlib, but has no entries). 



7fie Resident SVC Routines Option 



This option makes any of the type 3 and 4 svc routine load modules resident in 
storage. Some, or aU, of the modules associated with a svc service routine may 
be made resident. Placing the most frequently used svc load modules of a sys- 
tem service routine, such as open, in storage improves system performance. For 
type 3 svc load modules and initial type 4 svc load modules, the svc table entries 
associated with these modules are adjusted to reflect an entry point address 
rather than a relative track address. A resident svc load list is used by the xctl 
macro instruction for transfer of control between resident type 4 svc load modules. 

You list, in a member of sysI.parmlib, the type 3 and 4 svc load modules to be 
made resident. The member names for the standard lists are dearsvOO and 01. 
Such standard lists (shown later) are built by ibm in sysI.parmlib of the generated 
system. The creation of parameter library lists is discussed later in this chapter. 

If your system includes the multiple console support (mcs) function, to 
improve mcs performance you should add to the standard list igcOOOTb, the name 
of the first load module of the svc 72 routine. 

Note: Small (real storage) users should not use RSVCF. This further reduces real storage 
space available for paging. 



Storage Requirements 



The VSl Storage Estimates publication provides the byte requirements of type 
3 and 4 svc routines eligible to be made resident. The byte requirement of the 
code supporting the option is also provided. 
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List lEARSVOO 



The content of the ibm supplied standard list iearsvOO is: 



Module 

Name Function 

IGG0191L Open — Access method executor 

IGG0199L Open — Access method executor 

IGCOCOIC ABEND— Control module 

IGC0007B Router and control module 

IGG0CLC2 Catalog — Locate processing 

IGG0CLC7 Catalog — Third load of update, exit processing, and error handling 

IGG0CLF2 Catalog— SYSCTLG and BPAM directory formatter 

IGC0003B Allocate — Initialization 

IFG0202G Close — Taps volume disposition function 

IGG0193G Load required BDAM module 

IGC3503D DISPLAY/MONITOR processor 

IGG0193E Open executor number 3 

IGG0203A BDAM executor 

IGC0203E WTP routine 

IGG0193A Open executor number 1 

IGG0193C Opsn executor number 2 

IFG0197A Open — Access method executor return function 

IFG0200X Close — Access method executor 

IGCOEOIC ABEND — Subtask processing 

IGG0201N RCI close intercept 

IFG0195C Open — No tape label positioning function 

IFG0195K Open— Standard label INPUT/MOD header label 

2 function 

IFG0195H Open— Standard label LNPUT/MOD header label 

1 and 2 function 

IGC1203D Reply processor routine ( MCS ) 

IGC0403D Command routine 

IFG0200Z Close — Tape standard trailer label function 

IFG0196T Open— Standard label header label writing 

IFG0196Q Open — Tape standard label date protection 

IFG0196N Open — Standard label output security function 

IFG0194H Open — Tape volume verification function 

IGC0003E WTO/WTOR/WTP (SVC 35 processor) 

IGC0103E WTOR processor 

IGC0201F Purge (SVC 16— third load) 

IFG0552R EOV — Tape input standard trailer label and volume disposition functions 

IFG0195B Open — Standard label position function; 

INPUT/MOD header label 1 function 

IFG0194F Open — Tape mount verification function 

IFG0193B Open — Tape initial common function 

IFG0202F Close — Tape volume disposition function 

IGGC201X Close — Access method executor 

IGG0201A Close — ^Access method executor 

IGG0191G Open — Access method executor 

IFG0194I Open — Tape final common function 

IGG01993 Open — Access method executor 

IGG01991 Open— lOB and buffer construction 

IGG01915 Open — Access method executor 

IGG0290D Scratch— Format 4 DSCB (VTOC) updating 

IGG0290C Scratch— Format 5 DSCB (free space) updating 

IGG0290B Scratch— Format 6 DSCB updating, split-cylinder data sets 

IGG0299A Scratch— DSCB removal for formats 1, 2, and 3 

IGG0290A Scratch — Password protection interface, VTOC search 

IGG0290F Scratch — Volume mounting and verification 

IGG0290E Scratch — Mount message building 

IGG0325H Allocate (non-ISAM)— Updating format 4 DSCB and error handhng 

IGG0325G Allocate ( non-ISAM )— Update format 5 DSCB 

IGG0325E Allocate (non-ISAM)— Build format 1 and 3 DSCBs, non-split cylinder 

data sets 

IGG0325D Allocate ( non-ISAM )— Search free space 

IGG0325B Allocate (non-ISAM) — Request conversion and type determination 

IGG0325A Allocate— Duplicate format 1 DSCB search 

IGG029R1 RPS— Set up module 

IGC0003D Chain manipulator 

IGG0191C Open — Access method executor 

IGG0193I Open — Access method executor 

IGG0191I Open — Access method executor 

IGG01911 Open — Access method executor 
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Module 

Name Function 

IGG0191J Open — Access method executor 

IFG0232Z TCLOSE— Direct access final function 

IFG0232D TCLOSE— Direct access input and output functions 

IGG0191O Open — Access method executor 

ICCOGOIC Alternate entry point for ABEND control module 

IGCOBOIC ABEND— WTO purge processing 

IFG0201R Close — Direct access write DSCB and output user labels function 

IGG0191D Open — Direct access executor 

IGG0201W Close — Access method executor 

IFG0553P EOV — Direct access input initial function 

IGG0191F Open — Access method executor 

IGG0199W Open — Access method executor 

IGG0193K JES open executor function 

IGG0199G Open — Access method executor 

IFG0551H EOV — Initialize work area and determine device type 

IGG0203K JES close executor function 

IGG0201Y Close — Release work areas and buffers 

IGG0201Z Close— SAM executor 

IGG01917 Open — Second load of load executor 

IGG01910 Opsn- Load executor (first load) 

IGG019SL Open — Access method executor 

IGG0196B Open — Main executor ( second load ) 

IGG0191B Open— Main executor (first load) 

IFG0552X EOV — Direct access input concatenation/end-of-data function 

IFG0551F EOV— Initial read JFCB function 

IFG0202E Close— Write file mark 

IGG0196A Open — DEB construction ( second load ) 

IGG0191A Open— DEB construction (first load) 

IGG0191N Open — Access method executor 

IFG0195J Open— DSCB to JFCB merge ( direct access ) 

IFG0195A Open— DSCB to JFCB merge ( direct access ) 

IFG0194E Open— Unit selection and DSCB read 

IFG0196M Open— Merge DCB to JFCB 

IFG0196L Open— Merge and DCB exit routine 

IFG0196J Open— JFCB to DCB merge 

IGC0107B 1052 processor module 

IFG0202J Close — Restore system function 

IFG0202K Close — Restore user function 

IFG0196X Open (final)— JFCB to DSCB merge, SYSOUT limit, write JFCB 

functions; EXCP appendages 

IFG0200Y Close — Access method interface and write DSCB 

IGG0200G Gloss — Access method executor return/interface 

IFG0202L Close— Final load 

IFG0200W Close — Access method interface 

IFG0200V Close— Initialization and read JFCB and DSCB 

IGC0002* Close— Initial load 

IGCOOOIF Purge routine 

IGCOOOII Open— Initial load 

IGC0005E EOV— Initial load 

IGG0196I Open — Access method executor 

IFG0193A Open — Volume serial function 

IFG0196V Open — Access method determination 

IFG0198N Open— Rewrite JFCB and final load 

IFG0196W Open — Access method executor 

IGG0190S Open — Access method executor 

*The last (eighth) character is a 12 and punch. This character has no assigned graphic 
in EBCDIC. In BCD, the graphic is ? (the question mark). 



Also, modules specified with the sysgen macro svclib virtual= 
begin with igc or igx, are put on list iearsvOO. 



whose names 



List IEARSV01 



The IBM-supplied standard list iearsvOI contains modules specified with the 
sysgen macro svclib resednt= , whose names begin with igc or igx. If there 
are no module names for list iearsvOI, it is created as a null member (it exists on 
SYsl.PARMLiB, but has no entries ) . 
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The Resident Error Recovery Procedure Option 



This option places error recovery procedures in fixed storage. Some, or all, of the 
modules associated with the handling of an i/o error may be made resident. If 
an i/o device frequently requires erp processing, system performance improves 
if the error recovery procedures are made resident. The list of those error re- 
covery procedures that may be made resident is contained in the Storage 
Estimates publication. An i/o supervisor request for an error recovery pro- 
cedure will result in a search of the resident error recovery procedure list. If the 
error recovery procedure is resident, no fetch operation is required. 

You list, in a member of sys1.pabmt.tb, the module names of error recovery 
procedures to be made resident. The member name for the standard list is 
ieaigeOO. The error recovery procedures should be listed by expected frequency 
of use; the least used module is first in the list. Note: The format of the ebm- 
supphed ieaigeOO list contains the required library name, sysI.svcub, and no 
error recovery procedure names, unless the user specifies the names of ebps on 
the sysgen macro svcub. After system generation, ieaigeOO can be updated to 
indicate which error recovery procedures are to be made resident or an alter- 
nate list can be created. The creation of parameter Hbrary lists is discussed later 
in this section. 



Storage Requirements 



The VSl Storage Estimates publication provides the byte requirements of 
error recovery procedures that may be made resident. The byte requirement of 
the code supporting the option is also provided. 



List IEAIGEOO 



The IBM-supplied standard list ieaigeOO contains modules specified with the 
sysgen macro svclib besidnt= or vibtual^:, whose names begin with ige. If 
there are no module names for list ieaigeOO, it is created as a null member 
(it exists on sysI.pabmub, but has no entries). 



Creating Parameter Library Lists 



Use the iebupdte utility program to construct the required lists of load module 
names in the parameter library. Standard member names for these lists are shown 
in Figure bbo 1, plus lnklstOO for the link library list option. 

These are the member names that the nucleus initialization program reads from 
SYSl.PABMLiB if the option was either specified or defaulted to at sysgen and 
neither canceled nor modified by the operator's response to message ieaIOIa. 

Note: The nucleus initialization program (NIP) will search the system catalog to locate the 
SYS1.PARMLIB data set. If it is not found in the catalog, SYSl.PARMLIB is assumed 
to reside on the IPL volume. If no VTOC entry can be found, the operator will receive 
message IEA211I "OBTAIN FAILED FOR SYSl.PARMLIB DATA SET". Message IEA208I 
"fff FUNCTION INOPERATIVE" will foUow. The fff parameter-RAM, BLDL, RSVC, or 
RERP— shows which of the functions cannot be implemented. Processing will continue; how- 
ever, any resident functions dependent on parameter lists contained in the parameter library 
will be omitted from the system nucleus. 
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Except for lnklstOO, your input format (to iebupdte) for the lists is the same 
for all options, consisting of library identification followed by the load module 
names. You use 80-character records with the initial or only record containing 
the library identification. Continuation is indicated by placing a comma after 
the last name in a record and a nonblank character in column 72. Subsequent 
records must start in column 16. 

The initial record format (with continuation) is: 

1 72 

SYSl.LINKLIB 
[b . . .] SYSl.SVCLIB b . . . namel,name2,name3, ... X 

Subsequent records do not contain the library name. 

SYSl.LINKLIB indicates that linkage Hbrary load module names follow. 

SYsl.svCTJB indicates that svc library module names follow. 

You may also construct alternative lists and place them in the parameter 
library. Member names for these alternative lists are of the form: 

lEABLDxx for the BLDL option 

lEAIGGxx for the resident access method option 

lEARSVxx for the resident SVC routine option 

lEAIGExx for the resident error recovery procedure option 

LNKLSTOO for the Hnk library Hst option 
where xx can be any two alphameric characters. 

Use of the alternative lists is indicated by the operator at initialization time. 
The operator may indicate that the standard list is to be used; that alternative 
lists are to be used; or that the option(s) will not be used. In the last case, no 
resident bldl table, access method routines except several standard ones, svc 
routines or error recovery procedures are made resident. 



Example The following coding illustrates the format and content of a bldl option list that 

might be used to support the resident bldl table option. The operator, at ipl time, 
would have to indicate the member name, ieabldae to the system. The load 
module names listed are from the assembler (E), linkage editor, and scheduler 
components of the operating system. Note that the module names are listed in 
ascending collating sequence as required for the resident bldl option. Resident 
access method or svc modules should be listed in order of anticipated frequency 
of use. 

//BLDLIST EXEC PGM=IEBUPDTE,PARM=NEW 

//SYSPRINT DD SYSOUT=A 

//SYSUT2 DD DSNAME=SYSLPARMLIB,DISP=OLD 

//SYSIN DD * 

./ ADD NAME=:IEABLDAE,LIST=ALL 

./ NUMBER NEW1=01,INCR=02 

SYSl.LINKLIB GO,IEEGESTO,IEEGKlGM,IEEICIPE,IEEIC2NQ,IEEIC3JF, X 

IEEQOT00,IEFINTQS,IEFKl,IEFSD008,IEFW21SD,IEFXA, X 

IETASM,IETDI,IETE1,IETE2,IETE2A,IETE3, IETE3A,IETE4M X 
IETE4P,IETE4S,IETE5,IETE5A,IETE5E,IETE5P,IETINP,IETMAC X 
IETPP,IETRTA,IETRTB,IET07,IET071,IET08,IET09,IET09I, ' X 

IET10,IET10B,IET21A,IET2IB,IET21C,IET21D,IEWL,IEWSZOVR 
./ ENDUP 

/* 

Note: During initiahzation the operator reply "L" may be used in conjunction with a list 

specification and causes the content of the list to be printed. You should use this feature 

initially (especially with extensive lists) to easily identify format errors; for example, a 9 

character name, or incorrect name specifications. 
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Example of the ERP Option Tlie following coding illustrates the format and content ot an erp option list 
^'** that may be used to support the resident erp option. The operator, at ipl time, 

would have to indicate the member name, ieaigeOI, to the system. The load 
module names listed are the optical reader erps, write-to-operator, statistics up- 
date, i/o purge, OBR and sdr/ccr modules. The system must be sysgened with 
the RERP option to load any list. 

//ERPLIST EXEC PGM=IEBUPDTE,PARM=NEW 
//SYSOPRINT DD SYSOUT=A 

//SYSUT2 DD DSNAME=SYSl.PARMLIB,DISP=OLD 
//SYSIN DD * 

./ ADD NAME=IEAIGE01,LIST=ALL 

./ NUMBER NEW1=01,INCR=02 

SYSl.SVCLIB IGE0011B,IGE0011C,IGE0011D, X 

IGE0025C,IGE0125C,IGE0225C, X 

IGE0025D,IGE0025E,IGE0025F, X 

IGE0125F,IGE0525F 
./ ENDUP 



Link Library List Feature 



The hnk library hst (lnklstOO) enables you to concatenate up to 16 data sets, 
on multiple volumes, to form sysI.linklib. lnklstOO is included in the system 
when it is generated as a required member of sysLparmlib. If sysI.parmlib does 
not include the member lnklstOO, sysI.linklib is used as the system link library 
and a warning message is provided. 

Note: The amount of space required for SYSI.PARMLIB is discussed in the VSl Storage 
Estimates pubhcation. 

lnklstOO contains one member, sysI.linklib. After system generation you will 
have the option of adding members via the iebupdte utility program. Each 
member may have up to 16 extents. After making additions to sysI.svcub, 
sysI.linklib, or data sets concatenated to linklib via lnklstOO, and before using 
the additions, ipl should be performed to update the description of the link 
and/or svc library in storage. 

Your input format ( to iebupdte ) consists of 80 character records. Continuation 
is indicated by placing a comma after the last name in a record and a non- 
blank character in column 72. Subsequent records must start in column 16. The 
initial format is: 

[b...] SYSI.LINKLIB 

To add member names to lnklstKX), replace the initial record with: 

[b . . . ] SYSl.LINKLIB,namel,name2,name3, . . . 

The appropriate OS/VS Message Library publication describes the nip mes- 
sages associated with lnklstOO. 
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Output Separation 



In vsl, the system output writer can use the output 
separator facility to write separation records prior to 
writing the output of each job and optionally for 
printer-destined output, at the conclusion of writing 
the output. These separation records make it easy to 
identify and separate the various job outputs that are 
written contiguously on the same printer or card 
punch device. 

This section describes the output separator tfiat is 
supplied by ibm, and tells how to write your own. 



Section Outline 



Output Separation SEP 1 

Output Separation SEP 3 

Using an Output Separator SEP 3 

Functions of the IBM Output Separator SEP 3 

Punch-Destined Output SEP 3 

Printer-Destined Output SEP 4 

Creating an Output Separator Program SEP 4 

Parameter List SEP 4 

ProTamming Considerations SEP 5 

Output from the Separator Program SEP 6 

Using the Block Character Routine SEP 6 



Output Separation SEP 1 



SEP 2 OS/VSl Planning and Use Guide 



Output Separation 



In vsl, both the system output writer and the direct sysout writer may be used 
by a problem program to channel its output eventually to a printer or punch. 
When this is done, however, the system output stream goes uninterruptedly from 
one job to another, making it diflScult to separate the output of one job from that 
of another, unless output separation is provided for. 

The output separator facihty of the operating system provides a means of 
identifying and separating the output of various jobs processed by the same 
output unit. To do this, the separator writes separation records to the system 
output data set prior to the writing of each job's output. The end-of-job separator 
option, available only under the system output writer, assures the programmer 
that he has received all the output from his job. The separation records are 
written upon conclusion of writing a job's output. 

You can use the output separator that is supplied by ebm, or you can create 
and use your own output separator programs. 



Note: User-written output separator routines are not supported to RTAM devices. 



Using an Output Separator 



The output separator function operates under control of both the system output 
writer and the direct sysout writer. To use the function, the separator program 
must reside in the link library (sysI.linklib), and its name must be included as 
a parameter in either of the output writer procedures (the second part of the 
FARM field in the exec statement). Cataloged procedures for both writers are 
fully described in the System Reader, Initiator, and Writer Cataloged Procedures 
section. If the separator function is selected, the end-of-job separator option may 
be specified by placing the number of trailing separators to be written in the 
parameter field of the writer procedure. 



Functions of the IBM Output Separator 



The IBM-supplied output separator resides in the link library (sysI.linklib). 
When its name, iefosc06, is specified as a parameter in an output writer cata- 
loged procedure, that output writer uses it to separate job output. The type of 
separation provided by the separator depends on whether the output is punch- 
destined or printer-destined. 



Punch-Destined Output 



For punch-destined output, the iBM-supplied separator provides one to three 
specially punched cards (deposited in stacker 1) prior to the punched card 
output of each job ( see the description of the farm values of the exec statement 
in the section Output Writer Procedures). Each of these separator cards is 
punched in the following format: 

Columns 1 to 34 — blanks 

Columns 35 to 42 — jobname 

Columns 43 to 44 — blanks 

Column 45 — output classname 

Columns 46 to 80 — blanks 

Note: No end of job separators are available for punch-destined output. 
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Printer-Destined Output 



For printer-destined output, the iBM-supplied separator provides one to three 
specially printed pages prior to printing the output of each job (see the de- 
scription of the FARM values of the exec statement in the section Output Writer 
Procedures). Each of these three separator pages is printed in the following 
format: 

• Beginning at the channel 1 location (normally near the top of the page), the 
jobname is printed in block character format Over 12 consecutive hnes. The first 
block character of the 8-character jobname begins in column 11. Each block 
character is separated by 2 blank columns. 

• The next 2 lines are blank. 

• The output classname is printed in block character format covering the next 
12 lines. This is a 1-character name, and the block character begins in column 
55. 

• The remaining lines to the bottom of the page are blank. 

In addition to the preceding, a full line of asterisks (*) is printed twice (over- 
printed) across the folds of the paper. These lines are printed on the fold pre- 
ceding each of the 1 to 3 separator pages, and on the fold following the last 
page. This feature provides easy separation of job output in a stack of printed 
pages. 

For printer-destined output with the mM-supplied separator, you must include 
a channel 9 punch in addition to the channel 1 punch on the carriage control tape 
or in the forms control buffer (fcb). The channel 9 punch controls the location of 
the line of asterisks and should correspond to the bottom of the page. To print the 
line of asterisks on the fold of the pages, you must also offset the printer regis- 
tration. 

End-of-job separators provided by the iBM-supplied routine are identical to 
those printed prior to the output, except that no asterisks are printed after the 
last page. For remote devices that do not support channel 9 (for example, the 
IBM 2780), the output separator consists only of block letters (the line of asterisks 
is not printed ) . 



Creating an Output Separator Program 



Parameter List 



You can write your own output separator program by using the information pro- 
vided by either output writer and by conforming to the requirements explained 
in the following text. Your separator program, when added to the link library 
(sysLlinkub), is invoked by specifying its name as a parameter in the exec 
statement of the output writer cataloged procedure. 

Either output writer provides your separator program with a 4-word parameter 
list of needed information. When yoin: program receives control, register 1 con- 
tains the address of a 4-word parameter list, and the parameter Hst contains the 
following: 



Bytes 


0- 


3 


— In this word, byte contains switches that indicate the type of 
output unit. Byte 1 contains the number of separator pages or 
cards (in binary) requested, and bytes 2 and 3 are reserved for 
future use. 


Bytes 


4- 


7 


— This word is the address of the output DOB {data control block). 


Bytes 


8- 


11 


— This word is the address of an 8-character field containing the 
jobname. 


Bytes 


12- 


15 


— This word is the address of a 1-character field containing the out- 
put classname. 
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Programming Considera- 
tions 



In the parameter list, the three high-order bits of byte are switches that your 
separator program uses to determine the type of output unit. The first bit to the 
left is set to 1 if the output unit is a 1442 punch device. The second bit is set to 1 
if the output unit is a punch device or a tape device with punch-destined output. 
The third bit is set to 1 if the output unit is a printer or punch device. The result- 
ing bit combinations indicate the following: 

111 1442 punch device 

Oil 2520 or 2540 punch device 

001 1403, 1443, or 3211 printer device 

010 tape device with punch-destined output 

000 tape device with printer-destined output 

XXX . 1 . XX channel 9 not supported on this device 

XXX . ... 1 DSO 

XXX . . . 10 Separator routine entered after writing output 

The parameter list also points to the dcb for the output data set. This dcb is 
established for the queued sequential access method (qsam), and is already 
open when your separator program receives control. 

The address of the jobname and the address of the output classname are pro- 
vided in the parameter list so that this information may be used in the separation 
records written by your separator program. 

If you are using the (asynchronous) system output writer, your separator pro- 
gram, if specified in the output writer cataloged procedure, is brought in by a 
LINK macro instruction issued from module iefoscOI or iefosc02 of the output 
writer. Your separator program may be any size, but space must be provided 
at sysgen or overridden at ipl with a pakmub entry (see the appropriate VSl 
SYSGEN pubHcation for more details). If your job falls into a job class using 
the (synchronous) direct sysout writer, your separator program (if specified in 
the procedure) is brought into virtual storage by use of a load macro instruction. 
After performing separation on all devices required for the sysout data sets in 
that step, the program is released by means of a delete macro instruction. 

CAUTION 

3ince the separator program operates with the supervisor protection key, but in 

the program mode, your separator program must insure data protection during 

its execution. 

When writing a separator program, you must observe the following prograrn- 
ming requirements: 

• Your program must conform to the standard linkage conventions. This includes 
saving and restoring the contents of registers through 12, and 14. These 
registers can be preserved with the save and return macro instructions. When 
your program receives control, the address of a standard save area is in 
register 13. 

• Your program must use the put macro instruction in the locate mode to write 
separation records on the output data set. (This method is required by the 
QSAM DCB that is open for the output data set.) 

• Your program must establish its own synchronous error exit routine, and the 
address of this routine must be placed into the dcbsynad field of the output 
DCB. This gives control to your error exit routine in case an uncorrectable i/o 
error occurs while writing your program's output. 

• Your program should use the return macro instruction to return control to the 
output writer. Before returning, your program must free any main storage it 
obtained during its operation, and your program must place a return code 
(binary) in register 15. The return codes signify: 

— Successful operation. 

8 — Unrecoverable output error ( should be set if your error exit routine is 
entered). 
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Output from the 
Separator Program 



Your separator program can write any kind of separation identification. The 
jobname and the output classname for each job are available through the param- 
eter list for inclusion in your output, if desired. You can use an iBM-supplied 
routine that constructs block characters (explained later). You can punch as 
many separator cards or print as many separator pages as you deem necessary. 
The output from your separator program must conform to the attributes of 
the output data set. These attributes, which can be determined from the open 
output DCB pointed to by the parameter Hst, are: 

• Record format (fixed, variable, or undefined length). 

• Record length. 

• Type of carriage control characters (machine, ansi, or none). 

For printer-destined output, you can begin your separation records on the same 
page as the previous job output, or skip to any subsequent page. However, your 
separator program should skip at least one line before writing any records, be- 
cause in some cases the printer is still positioned on the line last printed. 

After completing the output of your separation records, your separator program 
should write sufficient blank records to force out the last separation record. This 
also allows your error exit routine to obtain control if an uncorrectable output 
error occurs while writing the last record. The requirements are: 

• One blank record for printer-destined output. 

• Three blank records for punch-destined output. 



Using the Block 
Character Routine 



For printer-destined output, your separator program can use an iBM-supplied 
routine to construct separation records in a block character format. This routine 
is a reenterable module named iefsd095, and resides in the module library 
(sysI.aosbO). 

The block character routine constructs block letters (A to Z), block numbers 
(0 to 9), and a blank. Your program furnishes the desired character string and 
the construction area. The block characters are constructed one line position at 
a time. Each complete character is contained in 12 lines and 12 columns; there- 
fore, a block character area consists of 144 print positions. For each position, the 
routine provides either a space or the character itself. 

The routine spaces 2 columns between each block character in the string. 
However, the routine does not enter blanks between or within the block charac- 
ters. Your program must prepare the construction area with blanks or other 
desired background before entering the block character routine. 

To use the iBM-supplied block character routine, your separator program 
executes the call macro instruction with the entry point name of iefsdOQS. Since 
the block characters are constructed one line position at a time, complete con- 
struction of a block character string requires 12 entries to the routine. Each time 
you enter the routine, you must provide the address of a 4-word parameter list 
in register 1. The parameter list must contain the following: 



Bytes 0- 3 
Bytes 4 - 7 

Bytes 8-11 
Bytes 12-15 



This word is the address of a field containing the desired character 

string in EBCDIC format. 

This word is the address of a full word field containing the line 

count as a binary integer from 1 to 12. This represents the line 

position to be constructed on this call. 

This word is the address of a construction area in main storage 

where the routine will construct a line of the block character 

string. The required length in bytes of this construction area is 

14n-2, where n represents the number of characters in the string. 

This word is the address of a fullword field containing, in binary, 

the number of characters in the string. 
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The Shared Direct-Access Device Option 



This section describes the Shared Direct Access 
Storage Device option (Shared dasd) of vsl. It des- 
cribes the functions of the option, its operating en- 
vironment, and volume acceptability. It also explains 
operating procedures and data set considerations that 
the systems programmer must be aware of in using 
the option. The section also describes a procedure 
for finding unit control block addresses necessary 
for using the reserve macro instruction: it also shows 
an assembler language subroutine that issues a 
RESERVE and can be called by a higher level language. 



Section Outline 
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The Shared Direct-Access Device Option 



The Shared dasd option allows computing systems to share direct access storage 
devices. Systems can share common data and consolidate data when necessary; 
no change to existing records, data sets, or volumes is necessary to use the facility. 
However, reorganization of volumes may be desirable to achieve better per- 
formance. Briefly, the sharing is accomplished by a two-channel or four-channel 
(3330 and 3333 only) switch which allows a shared control unit to be switched 
between channels from different systems. The switching is controlled by program 
use of the reserve macro instruction which reserves a shared device or volume 
for the use of one system until it is freed by the program's issuing a deq macro 
instruction. If a reserve macro instruction is used before the system in which 
the macro instruction is used has access to the shared device, the macro instruc- 
tion will take effect only after the system gains access to the device. 

The Shared dasd facility can only be included in a system at system generation 
time. A two-channel switch facility is shown in Figure shr 1. A four-channel 
switch facility is shown in Figure shr 2. 
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serializes use of the same resource between tasks in the system. 

Figure SHR 1. General Shared DASD Environment 
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In mulitprogramming systems, the RESERVE macro instruction also 
serializes use of the same resource between tasks in the system. 



Figure SHR 2. General Shared DASD Environment, 4-Channel Switch 
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System Configuration 



The Shared dasd option can be used with any combination of configurations of 
the operating system. Identical operating system configurations are not necessary 
for systems to share devices unless they share the system data set sysI.linklib. 
The option requires no additional equipment except the 2-channel switch, the 
4-channel switch, or the ibm 2844 Auxiliary Storage Control unit, which does 
not require the 2-channel switch. Any of your installation's applications data 
sets can be shared; sysctlg can be shared when it does not reside on a systems 
residence volume. The following system data sets cannot be shared: 



SYSl.SVCLIB 

SYSl.NUCLEUS 

SYSl.LOGREC 

SYSl.SYSJOBQE 

PASSWORD data set 

SYSl.SYSPOOL 

SYSl.SWADS 

SYSl.PAGE 



SYSCTLG (on system residence volume) 

SYSl.ACCT 

SYSl.MANX 

SYSl.MANY 



Devices that Can Be Shared The following control units and devices are supported by the Shared dasd option: 

1. IBM 2314 or 2319 Direct Access Storage Facility equipped with the 2-channel 
switch — IBM 2314 Disk Storage Module. 

2. IBM 2314 Direct Access Storage FaciUty combined with the ibm 2844 Auxiliary 
Storage Control— ibm Disk Storage Module. Device reservation and release are 
supported by this combination with or without the presence of tlie 2-channel 
switch. Two channels— one from System A and one from System B— may be 
connected to the combination. In addition, the 2-channel switch may be in- 
stalled in either or both of the control units, thus permitting as many as four 
systems to share the devices. 

3. IBM 2835 Storage Control Unit with 2-ehannel switch— ibm 2305-2 Fixed Head 
Storage Facility. 

4. IBM 3830-1 Storage Control Unit with 2-channel or 4-channel switch — ibm 
3330 Disk Storage. 

5. IBM 3830-2 Storage Control Unit with 2-channel or 4-channel switch — ibm 
3333 Disk Storage and Control. 

Alternate channels to a device from any one system may only be specified for 
the IBM 2314 Direct Access Storage Facility. 



Volume/Device Status 



The Shared dasd option requires that certain combinations of volume character- 
istics and device status be in effect for shared volumes or devices. One of the 
following combinations must be in effect for a volume or device: 



System A 

1. Permanently resident 

2. Reserved 

3. Removable 

4. Offlne 



Systems B,C,D 

Permanently resident 

Reserved 

Offline 

Removable or reserved 



If a volume/device is marked removable on any one system, the device must 
be in offline status on all other systems. The mount characteristic of a volume 
and/or device status may be changed on one system as long as the resulting com- 
bination is valid for other systems sharing the device. No other combination of 
volume characteristics and device status is supported or detected if present. 
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Volume Handling 



Volume handling on the Shared dasd option must be clearly defined since operator 
actions on the sharing systems must be performed in parallel. You should make 
sure that operators understand the following rules when the Shared dasd option 
is in effect: 

1. Operators should initiate all shared volume mounting and dismounting opera- 
tions. The system will dynamically allocate devices unless they are in reserved 
or permanently resident status. Only the former of the two can be changed by 
the operator. 

2. Mounting and dismounting operations must be done in parallel on all sharing 
systems. A vary offline must be effected on all systems before a device may 
be dismounted. 

3. Valid combinations of volume mount characteristics and device status for all 
sharing systems must be maintained. To ipl a system, a valid combination 
must be established before device allocation can proceed. This valid com- 
bination is established either by 

a. Specifying mount characteristics of shared devices in presres (See the 
section The PRESRES Volume Characteristics List.) 

b. Varying all sharable devices off line prior to issuing start commands and 
then following parallel mount procedures described in the appropriate 
Operators Library publication. 



Sharing Application Data 
Sets 



As indicated previously, all application data sets can be shared, but you must 
give special consideration to the classification of these data sets. It is recommend- 
ed that you classify your shared data sets as read only or read/write. A read-only 
data set may be read by all sharing systems but is never updated by them. 
A read/write data set may be read or written— updated by all sharing systems. 
Read-only data sets are not reserved for the duration of their use; read/write 
data sets must be reserved for data set protection. 

If a data set is seldom updated, but is read often, it is wise to classify it 
as read only. Minimizing reservation of devices will minimize the interference 
between systems. 

A shared data set may be updated, effecting a device reservation for the write 
operation only, if the records being read are independent of each other. An 
example of such a data set with independent records is a private job library. 
Such a library may be reserved for the write operation only as long as members 
are not being deleted. 

A system update time should be defined for updates to read-only data sets. 
For system update time the operator must vary ofiline, on all but one system, 
the device upon which the data set resides. Then the system update may be per- 
formed on the system to which that device is dedicated without any need to re- 
serve the device. Processing of data sets by the linkage editor and utility programs 
constitutes update runs-the data sets they process are regarded as read/write 
data sets. You may want to prepare a routine that will issue a reserve macro 
instruction, invoke the program to be executed, and issue a deq macro instruc- 
tion after program execution. 
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There is no protection for shared data sets across job steps. That is, the 
EESERVE and deq for a data set must be done within each step (task); if devices 
are still reserved at the end of a task, device release is effected. Therefore, it 
is possible for one system to reserve a device and update a data set on that 
device between the execution of two steps in the other systems which are using 
that data set. There is no guarantee that a data set will remain unchanged between 
execution of steps. 



Reserving Devices 



The EESERVE macro instruction is used to reserve a device for use by a particular 
system; it must be issued by each task needing device reservation. The reserve 
macro instruction protects the issuing task from interference by other tasks in 
the system. Each task issuing the reserve macro instruction must also use the 
DEQ macro instruction to release the device; two reserve instructions for the 
same resource without an intervening deq will result in an abnormal termination 
unless the second one specifies the keyword parameter bet=. ( If a restart occurs 
when a reserve is in effect for devices, the system will not restore the reserve; 
the user's program must reissue the reserve.) Even if a deq is not issued for a 
particular device, termination routines in all operating system configurations 
will release devices reserved by a terminating task. 



The SMC Parameter of fhe 
ENQ Macro Instrucfion 



The Set-Must-Complete (smc) parameter available with the enq macro in- 
struction may also be used with reserve; this parameter is discussed in the sec- 
tion The Must-Complete Function. 



RESERVE Macro Instruction 



The use of the reserve macro instruction is explained here: 



[symbol] RESERVE {qname address, rname address, s ' 

[rname length] , SYSTEMS) 



(test i 

, RET= -JUSE > 
(HAVE). 



,UCB = pointer address 



qname 

is the address in storage of an 8-character name. Every task (within the 
system) issuing reserve against the same resource (data and device) must 
use the same qname-rname combination to represent the resource. The qname 
should not start with sys. 

rname address 

is the address in storage of a name used in conjunction with the qname 
to represent the resource. The rname can be qualified, and may be 1 to 255 
bytes in length. 



E_ 

S 



specify either exclusive control of the resource (E); or shared control with 
other tasks in the system (S). E is the default condition. 
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rname length 

is the length, in bytes, of rname. If omitted, the assembled length of rname 
is used. If zero (0) is specified, the length of rname must be contained in 
the first byte of the field designated by the rname address. 

SYSTEMS 

specifies that the resource represented by qname-rname is known across 
systems as well as within the system whose task is issuing reserve, that is 
the resource is shared between systems. 



RET= 



specifies a conditional request for all of the resources named in the reserve 
macro instruction. If the operand is omitted, the request is unconditional. The 
types of conditional requests are as follows: 
test 

tests the availability status of the resources but does not request control 

of the resources. 

USE 

specifies that control of the resources be assigned to the active task 
only if the resources are immediately available. If any of the resources 
are not available, the active task is not placed in a wait condition. 

HAVE 

specifier that control of the resources is requested only if a request has 

not been made previously for the same task. 
Return codes are provided by the control program only if ret=test, Ret= 
USE, or RET^HAVE is designated; otherwise, return of the task to the active 
condition indicates that control of the resource has been assigned to the 
task. Return codes are identical to those supplied by the enq macro instruc- 
tion (see the Supervisor Services and Macros publication). 

\!CB=pointer address 

This keyword specifies either: 

1. The address of a fullword that contains the address of the Unit Control 
Block (uob) for the device to be reserved. 

2. A general register (2-12) that points to a fullword containing the address 
of the unit control block for the device to be reserved. 

To use the Shared dasd option in higher level languages, you may wish to 
write an assembler language subroutine to issue the reserve macro instruction. 
You should pass to this subroutine the following information: ddname, qname 
address, rname address, rname length, and ret parameter. 



T/ie EXTRACT A^acro 
Insiruci'ion 



The EXTRACT macro instruction is used to obtain the address of the task input/ 
output table (tiot) from which the ucb address can be obtained. This section 
explains some procedures for finding the ucb address. 



Releasing Devices 



The DEQ macro instruction is used in conjunction with reserve just as it is used 
with enq. It must describe the same resource and its scope must be stated as 
SYSTEMS; however, the ucB=pointer address parameter is not required. If the 
DEQ macro instruction is not issued by a task which has previously reserved a 
device, the system will free the device when the task is terminated. 
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Preventing interlocks 



Certain precaution must be taken to avoid system interlocks when the eesehve 
macro instruction is used. The more often device reservations occur in each 
sharing system, the greater the chance of interlocks occurring. Allowing each 
task to reserve only one device minimizes the exposure to interlock. The system 
cannot detect interlocks caused by program use of the eeserve macro instruction 
and enabled wait states will occur on the system(s). 



Volume Assignment 



Since exclusive control is by device, not by data set, you must consider which 
data sets reside on the same volume. In this environment it is quite possible for 
two tasks in two different systems— processing four different data sets on two 
shared volumes— to become interlocked. For example, data sets X^ and X^ reside 
on device X and data sets Y^ and Y2 reside on device Y. Task A in system A 
reserves device X in order to use data set X^; task B in system B reserves 
device Y in order to use data set Y^. Now task A in system A tries to reserve 
device Y in order to use data set Y2 and task B in system B tries to reserve 
device X in order to use data set X2. Neither can ever regain control and thus, 
will never complete normally and the job(s) should be canceled. In any en- 
vironment in which job step time limits are specified, the task(s) in the interlock 
would be abnormally terminated when the time limit expires. Moreover, an 
interlock could mushroom, encompassing new tasks as these tasks try to reserve 
the devices involved in the existing interlock. 



Program Libraries 



When assigning program Hbraries to shared volumes, precaution must be taken 
to avoid interlock. For example, svclib for system A resides on volume X, while 
svcLiB for system B resides on volume Y. Task A in system A invokes a direct access 
device space management function for volume Y, resulting in that device being 
reserved. Task B in system B invokes a similar function for volume X, reserving 
that device. However, since the dadsm functions are transient svcs, each load 
module transfers to another load module via xctl. Since the svclib for each sys- 
tem resides on a volume reserved by the other system, the xctl macro instruction 
cannot complete the operation, therefore an interlock occurs. In this particular 
case, since no access to svclib is possible, both systems will eventually enter an 
enabled wait state. 



Providing the Unit Control 
Block Address to RESERVE 



The extract macro instruction is used to obtain information from the Task 
Control Block (tcb). The address of the tiot can be obtained from the tcb in 
response to an extract macro instruction. Prior to issuing an extract macro 
instruction, the user sets up an answer area in storage which is to receive 
the requested information. One full word is required for each item to be provided 
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by the control program. If the user wishes to obtain the tiot address he must 
issue the following form of the macro instruction: 

EXTRACT answer-area address, FIELDS=TIOT 

The address of the tiot is then returned by the control program, right-adjusted, 
in the full word answer area. 

The TIOT is constructed by job management routines and resides in storage 
during step execution. The tiot consists of one or more dd entries, each of 
which represents a data set defined by a dd statement for the jobstep. Each 
entry includes the dd name. Associated with each dd entry is the ucb address of 
the associated device. In order to find the ucb address, the user must locate 
the dd entry in the tiot corresponding to the dd name of the data set for which 
he intends to issue the reserve macro instruction. 

The UCB address may also be obtained via the deb and dcb. The Data Control 
Block (dcb) is the block within which data pertinent to the current use of the 
data set is stored. The address of the Data Extent Block (deb) is contained at 
offset 44 decimal after the dcb has been opened. The deb contains an extension 
of the information in the dcb. Each deb is associated with a dcb, and the two 
point to each other. 

The deb contains information concerning the physical characteristics of the 
data set and other information that is used by the control program. A device 
dependent section for each extent is included as part of the deb. Each such ex- 
tent entry contains the ucb address of the device to which (that portion of) the 
data set has been allocated. In order to find the ucb address, the user must locate 
the extent entry in the deb for which he intends to issue the reserve macro in- 
struction. (In disk addresses of the form mbbcchhr, the m indicates the extent 
number starting with 0. ) 

Following are suggested procedures for finding the ucb address of the device 
to be reserved. 

If the data set is a multivolume sequential data set, it must be assumed that 
all jobs will process that data set in a sequential manner starting with the first 
volume of the data set. In this case, by issuing a reserve for the first volume 
only, the user effectively reserves all the volumes of the data set. 

For data sets using the queued access methods in the update mode or for 
unopened data sets: 

1. Extract the tiot from the tcb. 

2. Search the tiot for the dd name associated with the shared data set. 

3. Add 16 to the address of the dd entry found in step 2. This results in a 
pointer to the ucb address in the tiot, 

4. Issue the reserve macro specifying the address obtained in step 3 as the 
operand of the ucb keyword. 

For opened data sets: 

1. Load the deb address from the dcb field labeled dcbdebad. 

2. Load the address of the field labeled debdvmod in the deb obtained in step 
1. The result is a pointer to the ucb address in the deb, 

3. Issue the reserve macro specifying the address obtained in step 2 as the 
operand of the ucb keyword. 
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For BSAM data sets the user may reserve the device at any point in his process- 
ing in the following manner: 

1. Open the data set successfully. 

2. Convert the block address used in the eead/write macro to an actual device 
address of the form mbbcchhe. 

3. Load the deb address from the dcb field labeled dcbdebad, 

4. Load the address of the field labeled debdvmod in the deb. 

5. Multiply the "M" of the direct access address by 16. 

6. The sum of steps 4 and 5 is the address of the correct extent entry in the 
DEB for the next bead/write operation. The sum is also a pointer to the ucb 
address for this extent. 

7. Issue the reserve macro specifying the address obtained in step 6 as the 
operand of the ucb keyword. 

If the data set is an isam data set, qisam in the load mode should be used 
only at system update time. Further, if it is a multivolume isam data set, it must 
be assumed that all jobs will access the data set through the highest level index. 
The indexes should never reside in storage when the data set is being shared. 
In this case, by issuing a reserve macro for the volume on which the highest 
level index resides, the user effectively reserves the volumes on which the prime 
data and independent overflow areas reside. The following procedures may be 
used to achieve this: 

1. Open the data set successfully. 

2. Locate the actual device address (mbbcchh) of the highest level index. This 
address can be obtained from the dcb. 

3. Load the deb address from the dcb field labeled dcbdebad. 

4. Load the address of the field labeled debdvmod in the deb. 

5. Multiply the "M" of the actual device address located in step 2 by 16. 

6. The sum of steps 4 and 5 is the address of the correct extent entry in 
the DEB for the highest level index not in core. This extent entry is also a 
pointer to the ucb address. 

7. Issue the reserve macro specifying the address obtained in step 6 as the 
operand of the ucb keyword. 



RES and DEQ Subroutines The following assembler language subroutine may be used by Fortran, cobol, 

or assembler language programs to issue the reserve and deq macro instructions. 
Parameters that must be passed to the resdeq routine, if the reserve macro in- 
struction is to be issued, are: 

DDNAME 

Address of the eight character name of the ddcard for the device that you wish 
to reserve. 

QNAME 

Address of an 8-character name. 

RXAME LENGTH 

Address of one byte ( a binary integer ) that contains the rname length value. 
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RNAME 

Address of a name from 1 to 255 characters in length. 
The DEQ macro instruction does not require the uc:B=pointer address as a para- 
meter. If the DEQ macro is to be issued, a fuUword of binary zeros must be 
placed in the ddname field before control is passed. 



RESDEQ 



CSECT 

SAVE 

BALR 

USING 

ST 

LA 

ST 

LR 

LR 

L 

CLC 

BE 



(14,12),T 

2,0 

* 2 

13,SAVE+4 

1],SAVE 

11,8(13) 

13,11 

9,1 

3,0(9) 

0{4,3),=F'O' 

WANTDEQ 



SAVE REGISTERS 

SET UP ADDRESSABILITY 



ADDRESS OF MY SAVE AREA IS STORED 
IN THIRD WORD OF CALLER'S SAVE AREA 
ADDRESS OF MY SAVE AREA 
PARAMETER LIST ADDRESS POINTER 
ADDRESS OF PARAMETER LIST 
DDNAME PARAMETER OR WORD OF ZEROS 
WORD OF ZEROS IF DEQ IS REQUESTED 



*PROCESS FOR DETERMINING THE UCB ADDRESS USING THE TIOT 

XR 11,11 REGISTER USED FOR DD ENTRY 

EXTRACT ADDRTIOT,FIELDS=TIOT 

7,ADDRTIOT ADDRESS OF TASK I/O TABLE 



NEXTDD 



L 

LA 

L 

CLC 

BE 

IC 

LA 

CLC 

BNE 

ABEND 

LA 



7,24(7) 

5,0(3) 

0(8,5), 4(7) 

FINDUCB 

11,0(7) 

7,0(7,11) 

0(4,7),=F'0' 

NEXTDD 

200,DUMP 

8,16(7) 



ADDRESS OF FIRST DD ENTRY 
ADDRESS OF DDNAME 
COMPARE DDNAMES 

LENGTH OF DD ENTRY 
ADDRESS OF NEXT DD ENTRY 
CHECK FOR END OF TIOT 



DDNAME IS NOT IN TIOT, ERROR 
FINDUCB LA 8,16(7) ADDRESS OF WORD IN TIOT THAT 

* CONTAINS ADDRESS OF UCB 

♦PROCESS FOR DETERMINING THE QNAME REQUESTED 
WANTDEQ L 7,4(3) ADDRESS OF QNAME 

MVC QNAME(8),0(7) MOVE IN QNAME 

♦PROCESS FOR DETERMINING THE RNAME AND THE LENGTH OF RNAME 



L 

MVC 
L 
STC 



L 

BCTR 

EX 

CLC 

BE 

RESERVE 

B 

ISSUEDEQ DEQ 

RETURN L 

RETURN 
BCR 

MOVERNAM MVC 

ADDRTIOT 

SAVE 

QNAME 

RNAME 

RNLEN 



DC 
DS 
DS 
DS 
DC 
END 



7,8(3) ADDRESS OF RNAME LENGTH 

RNLEN+3(1),0(7) MOVE BYTE CONTAINING LENGTH 

7,RNLEN 

7,RNAME STORE LENGTH OF RNAME IN THE 

FIRST BYTE OF RNAME PARAMETER 

FOR RES/DEQ MACROS 
6 12(3) ADDRESS OF RNAME REQUESTED 

t'o subtract one FROM RNAME LENGTH 

7^M0VERNAM MOVE IN RNAME 

0(4,3),=F'0' 
ISSUEDEQ 

( QNAME,RNAME,E,0,SYSTEMS ) ,UCB= ( 8 ) 
RETURN 

( QNAME,RNAME,0,SYSTEMS ) 

13,SAVE+4 RESTORE REGISTERS AND RETURN 

( 14,12 ),T 
15,14 

RNAME+1(0),0(6) 
F'O' 
18F 
2F 

CL256 
F'O' 



SHR 12 OS/VSl Planning and Use Guide 



System Macro Instructions 



This section contains the description and formats of 
macro instructions that allow you either to modify 
control blocks or to obtain information from control 
blocks and system tables. 
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How to Read a Job File Control Block 



To accomplish the functions that are performed as a result of an open macro 
instruction, the open routine requires access to information that you have supplied 
in a data definition (dd) statement. This information is stored by the system in 
a job file control block ( jfcb). 

Usually, the programmer is not concerned with the jfcb itself. In special ap- 
plications, however, you may find it necessary to modify the contents of a jfcb 
before issuing an open macro instruction. To assist you, the system provides the 
EDjFCB macro instruction. This macro instruction causes a specified jfcb to be 
read into main storage from the job queue in which it has been stored. Format 
and field description of the jfcb is contained in the VSl System Data Areas publi- 
cation. 

When subsequently issuing the open macro instruction, you must indicate, by 
specifying the type=j option, that you have supplied a modified jfcb to be used 
during the initialization process. 

The JFCB is returned to the job queue by the open routine or the openj routine, 
if any of the modifications in the following list occur. These modifications can 
occur only if the information is not originally in the jfcb. 

• Expiration date field and creation date field merged into the jfcb from the 

DSCB. 

• Secondary quantity field merged into the jfcb from the dscb. 

• dcb fields merged into the jfcb from the dscb. 

• dcb fields merged into the jfcb from the dcb. 

• Volume serial number fields added to the jfcb. 

• Data set sequence number field added to the jfcb. 

• Number of volumes field added to the jfcb. 

If you make these, or any other modifications, and you want the jfcb returned 
to the job queue, you must set the high-order bit of field jfcbmask-1-4 to one. 
This field is in the jfcb. Setting the high-order bit of field jFCBMASK-f-4 to zero 
does not necessarily suppress the return of the jfcb to the job queue. If the open 
or openj routines have made any of the preceding modifications, the jfcb is re- 
turned to the job queue. To inhibit writing the jfcb back to the job queue 
during an openj, the field jfcbtsdm should be set to X'08' prior to issuing the 
OPEN macro. 



OPEN— Prepare the Data 
Control Block for 
Processing (S) 



The OPEN macro instruction initializes one or more data control blocks so that 
their associated data sets can be processed. 

A full explanation of the operands of the open macro instruction is contained in 
the OS/VS Data Management Macro Instructions publication. The type=j option, 
because it is used in conjunction with modifying a jfcb, should be used only by 
the system programmer or only under his supervision. 
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CIRB— Create IRB for Asynchronous Exit Processing 



The CIRB macro instruction is included in sysI.maclib and must be included in 
your system at system generation time if you intend to use it. The issuing of this 
macro instruction causes a supervisor routine (called the exit effector routine) 
to create an interruption request block ( irb ) . In addition, other operands of this 
macro instruction may specify the building of a register save area and/or a work 
area to contain interruption queue elements, which are used by supervisor routines 
in the scheduling of the execution of user exit routines. 



Name 


Operation 


Operand 


[symbol] 


CIRB 


(EP = addrxV KEY=^-^^!-, MODE = 
^ ' iSUPRi 

[stab = code,] ' 

JSVAREA = -^^^[, [WKAREA = value] 
f YES ) 


iSUPR i 



EP 



KEY 



Specifies the entry point address of the user's asynchronous exit routine. 

specifies whether the user's asynchronous routine will operate with a cpu pro- 
tection key established by the supervisory program ( supr ) or with a protec- 
tion key obtained from the task control block of the task for which the macro 
instruction is issued (pp). 

MODE 

specifies whether the user asynchronous routine will be executed in the 
problem program (pp) state or in a supervisory (supr) state. 

STAB 

indicates the status condition of the interruption request block. The 'code* 

parameter may be either of the following: 

(re) to indicate that the irb is reusable in its current form. 

(dyn) to indicate that the storage area assigned to the irb is to be made 

available (that is, freed) for other uses when the asynchronous exit 

routine is completed. 

SVAREA 

specifies whether a register save area (of 72 bytes) is to be obtained from 
the storage assigned to the problem program. If it is, the address of 
this save area is placed in the irb. The asynchronous exit routine then follows 
the system register saving convention of using the save and return macro 
instructions. In this manner, a generalized subroutine can be used as an 
asynchronous exit routine. 

WKAREA 

specifies the number of double words (given as a decimal value) required for 
an area in which the routine issuing the macro instruction can construct inter- 
ruption queue elements. 
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SYNCH— Synchronous Exits to Processing Program 



The SYNCH macro instruction is a system macro instruction that permits control 
program supervisor call ( svc ) routines to make synchronous exits to a processing 
program. 



Name 


Operation 


Operand 


[symbol J 


SYNCH 


[ entry-point { 
( (15) ) 



entry-point 

specifies the address of the entry point for the processing program that is to 
be given control. 

If (15) is specified, the entry-point address of the processing program 
must have been pre-loaded into parameter register 15 before execution of 
this macro instruction. 



SYNCH Macro Definition 





MACRO 




&NAME 


SYNCH 


&EP 




AIF 


C&EP' EQ ' ' ) .El 




AIF 


C&EP' (1,1) EQ ' (') .REG 


&XAME 


LA 


15,&EP 




AGO 


.SVC 


.REG 


AIF 


C&EF EQ ' (15) ' ) .NAMEIT 


&NAME 


LR 


15AEP(1) 


.SVC 


SVC 
MEXIT 


12 


.NAMEIT ANOP 




&NAME 


SVC 
MEXIT 


12 


.El 


IHBERMAC 
MEND 


27,405 



LOAD ENTRY POINT ADDRESS. 



LOAD ENTRY POINT ADDRESS. 
ISSUE SYNCH SVC 



ISSUE SYNCH SVC 



Programming Notes 



In general, you use the synch macro instruction when a control program in the 
supervisor state is to give temporary control to a processing program routine, and 
you expect the processing program to return control to the supervisor state. The 
program to which control is given must be in storage when the macro instruction 
is issued. The use of this macro instruction is similar to that of the balr instruction 
in that register 15 is used for the entry point address. When the processing pro- 
gram returns control, the supervisor state bit, the storage protection key bits, 
the system mask bits and the program mask bits of the program status word are 
restored to the settings they had before execution of the synch macro instruction. 



Example 



As a result of an open macro instruction, label processing may be carried out 
to a point at which a user's processing program indicates that private processing 
is desired (or necessary). The control program's open routine then will issue a 
synch macro instruction giving the entry point of the subroutine required for 
the user's private label processing. 
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STAE— Specify Task Asynchronous Exit 



The STAE macro instruction permits control to be returned to a user exit routine 
when a task is scheduled for abend. When you issue the stae macro instruction, 
a STAE control block (scb) is created and initialized with the address of your 
user exit routine. If you issue multiple stae requests within the same program, the 
SCB associated with the last issued stae request becomes the active scb: it will be 
the first to gain control when an abend is scheduled. If the active scb is cancelled, 
the preceding scb, if there is one, will become the active scb. 

Notes: 

• You cannot cancel or overlay an SCB not created by your program. 

• The execution of a LINK macro instruction does not cancel the active SCB for the pro- 
gram in control. 



STAE— Execute and 
Standard Form 



Name 



[symbol] 



Operation 



STAE 



Operand 




,PARAM = 



J QUIESCE 
HALT 
NONE 



list 
address 



,XCTL 



YES, 



NO 



,ASYNCH = 



MF = (E, [remote list address] [(1)]) 



exit address 

specifies the address of a stae exit routine to be entered if the task issuing 
this macro instruction terminates abnormally. If is specified, the last see 
created is canceled and the previously created scb becomes current. The 
address may be loaded into one of the general registers (r^) 2 through 12. 

Note: If you use the execute form of the macro and specify a zero, the exit address 
in the parameter list will be zeroed. 



OV 



CT 



indicates that the parameters passed in this stae macro instruction are to 
overlay the data currently in the scb. 

indicates the creation of a new active scb. 



PARAM= 

specifies the address of a parameter list containing data to be used by the 
STAE exit routine when it is scheduled for execution. The address may be 
loaded into one of the general registers (r^) 2, through 12. 

XCTL=YES 

indicates that the stae macro instruction will not be canceled if an xctl 
macro instruction is issued. 

xctl=no 

indicates that the stae macro instruction will be canceled if an xctl is issued. 
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FUEGE=QUIESCE 

indicates that all active input/output operations will be purged with the 
quiesce option. If this fails, active input/output operations will be purged 
with the halt option. 

Note: If you use the execute form of the STAE macro instruction and omit the PURGE 
parameter, QUIESCE will not be the default; the option specified for the preceding use 
of STAE will be used. 

PUEGE=HALT 

indicates that all active input/output operations will be purged with the 
halt option. 

PUEGE=NONE 

indicates that all active input/output operations will not be purged 

ASYNCH=NO 

indicates that asynchronous exit processing will be prohibited while stae 
exit processing is being done. 

ASYNCH=YES 

indicates that asynchronous exit processing will be allowed while stae exit 
processing is being done. 
mf=(e, [remote list address] [{1)1) 

indicates the execute form of the stae macro instruction using a remote 
parameter list. The address of the remote parameter hst can be loaded into 
register 1, in which case mf=(e, (1) ) should be coded. 

Note: When using the execute form of the stae macro instruction and omitting the 
ASYNCH parameter, the option specified for the preceding use of stae will be used. 



STAE— List Form Use the list form of the stae macro instruction to construct program parameter 

hsts. The description of the execute and standard form applies to the list form 
with the following exceptions: 
exit address 

any address that may be M^Titten in an A-type address constant. 

MF=L 

indicates the list form of the stae macro instruction. 

You should be aware of several conditions when you use the purge and asynch 
parameters of the stae macro instruction: 

• If your user exit routine requests a supervisor service that requires asyn- 
chronous interruptions to complete its normal processing, you must specify 

ASYNCH=YES. 

• You must specify asynch=yes if you use an access method that requires 
asynchronous interruptions to complete its normal processing and you have 
specified purge^quiesce. 

• If you are using the Indexed Sequential Access Method (isam) and specify 
purge=halt, only the i/o event for which the purge is done will be posted. 
Subsequent ecbs will not be posted; this causes the isam check routine to treat 
purged input/output operations as waiting input/output operations and you 
will never get past the check in your program. 

• You must specify asyxch=yes when you have the following combination of 
conditions: an access method that requires asynchronous interruptions to 
complete its normal processing, a specification of purge=xone, and a request 
of check in your user exit routine. 
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If you specify putige=halt and an isam data set is being updated when a 

failure occurs, part of the data set may be destroyed. 

If quiesced input/output operations are not restored and you are using isam, 

the ISAM CHECK routine will treat purged input/output operations as waiting 

input/output operations and part of the isam data set may be destroyed if 

it is being updated when a failure occurs. 

If input/output operations are allowed to complete while your exit routine 

is in progress and there is a failure in the i/o processing, you will encounter an 

ABEND recursion when the i/o interrupt occurs. This can be misleading because 

it will appear that your exit routine failed while the actual cause of the failure 

was in the i/o processing. 



Programming Notes 



When control is returned to the user after the stae macro instruction has been 
issued, register 15 contains one of the following return codes: 



Code Meaning 

00 An SCB is successfully created, overlaid, or canceled. 

04 Storage for an SCB is not available. 

08 The user is attempting to cancel or overlay a non-existent SCB, or is issuing a STAE 

in his STAE exit routine. 
OC The exit routine or parameter list address is invalid. 

10 The user is attempting to cancel or overlay an SCB not associated with his level 

of control. 

When a program with an active stae environment encounters an abend situa- 
tion, control is returned to the user through the abend/stae interface routine at 
the STAE exit routine address. The register contents are as follows: 

• Register 0: 

Code Indication 

Active I/O at time of ABEND was quiesced and is restorable. 

4 Active I/O at time of ABEND was halted and is not restorable. 

8 No I/O was active at the time of the ABEND. 



Register 1: Address of a 104-byte work area: 



STAE exit routine parameter 
list addr or 



ABEND completion code 



8 
16 
24 



PSW at time of ABEND 



Last P/P PSW before ABEND 



Registers 0-15 at time of ABEND (64 bytes) 



If problem program issued stae: 



88 
96 



Name of ABENDing program or 



Entry point addr of ABENDing 
program 
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If supervisor program issued stae: 



88 



96 



Request block address of 
ABENDing program 



• Registers 2-12: Unpredictable. 

• Register 13: Address of a supervisor save area, 
o Register 14: Address of an svc 3 instruction. 

• Register 15: Address of the stae exit routine. 

Registers 13 and 14, if used by the stae exit routine, must be saved and re- 
stored prior to returning to the calling program. Standard subroutine linkage 
conventions are employed. 

If storage was not available for the work area, the register contents upon 
entry to the stae exit routine are as follows: 

• Register 0: 12. 

• Register 1: abend completion code, as in the tcbcmp field. 

• Register 2: Address of stae exit parameter list= 

The stae exit routine may contain an abend, but must not contain either a 
STAE or an attach macro instruction. At the time the abend is scheduled, the 
stae exit routine must be resident as part of the program issuing stae, or brought 
into storage via the load macro instruction. 



Scheduling of STAE 
Exit and Retry Routines 



j^acii STAE exit lOutme is representeu. by one or more stae cojiitroi diOcks ^^ scbs j , 
Each stae control block is queued in a last-in, first-out order to the tcb (tcbnstae 
field) of the task within which they were created. 

If a task is scheduled for abnormal termination, the exit routine specified by 
the most recently issued stae macro instruction (represented by the highest stae 
control block on the queue) is given control and executes under a program re- 
quest block created by the synch service routine. The stae exit routine must 
specify, by a return code in register 15, whether a retry routine is to be scheduled. 
If no retry routine is to be scheduled (return code=0), abnormal termination 
continues. 

If the STAE exit routine indicates that a retry routine has been provided (re- 
turn code=4), register must contain the address of the retry routine and 
register 1 must contain the address of the same work area passed to the exit 
routine. (The first word of the work area may be modified by the exit routine 
to point to another parameter list in the partition. ) The stae control block is freed 
and the request block queue is purged of all rbs from the rb of the program 
that is being terminated up to, but not including, the rb of the prograan that 
issued the stae macro instruction. This is done by placing an svc 3 instruction in 
the old psw field of each rb to be purged. In addition, open dcbs which can be 
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associated with the purged rbs are closed, and queued i/o requests associated 
with these dcbs being closed are deleted from the i/o restore chain. 

The KB purge is an attempt to cancel the effects of partially executed pro- 
grams that are at a lower level in the program hierarchy than the program under 
which the retry will occur. However, certain effects on the system will not be 
canceled by this rb purge. Examples of these effects are as follows: 

• Subtasks created by a program to be purged. 

• Resources allocated by the enq macro instructions. 

• DCBS that exist in dynamically acquired storage. 

When your stae exit routine gains control, it can examine the code in register 
to determine if there were active input/output operations at the time of the 
ABEND and if the input/output operations are restorable. If there are quiesced 
restorable input/output operations, you can restore them, in the stae retry 
routine, by using word 26 in the work area. Word 26 contains the link field 
passed as a parameter to svc restore, svc restore is used to have the system re- 
store all i/o requests on the i/o restore chain. 

You can selectively restore specific i/o requests on the i/o restore chain by 
using word 2 in the work area. Word 2 contains the address of the first i/o 
block on the i/o restore chain. You can use this address as a starting point for 
issuing Excp for the i/o requests that you want to restore. 

In supervisor mode, you may want the failing task to remain in its present 
status and not be reestablished. A retry routine may be scheduled without a 
purge of the rb chain by returning to the abend/stae interface routine with an 
8 in register 15, and registers and 1 initialized as previously described. If the 
stae retry routine is scheduled, the system automatically cancels the active scb 
and the preceding scb, if there is one, will become the active scb. If you want 
to maintain stae protection against abend, you must re-establish an active scb 
within the retry routine, or you must issue multiple stae requests prior to the 
time that the retry routine gains control. 

The stae exit routine must specify by a return code in register 15 one of the 
following: 

Return Code Action to be Taken 

No retry provided. Abnormal termination is to continue. 

4 A retry routine is to be scheduled and the request block queue is to be 

purged. 

8 A retry routine is to be scheduled but the request block queue is not to be 

purged (if the user is not in supervisor mode, this return code will be 
ignored and abnormal termination processing continues). 

When the kb queue is not to be purged, a new prb is created for the retry 
routine and placed on the rb queue immediately after the svrb for the abend 
routine, so that when the abend routine returns via an svc 3 instruction the retry 
routine will receive control. 

If the RB queue is to be purged, the stae retry routine is executed under the 
prb that issued the stae being processed for this abnormal termination. 
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Like the stae exit routine, the stae retry routine must be in storage when 
the exit routine determines that retry is to be attempted. If not aheady resident 
within your program, the retry routine may be brought into storage by the load 
macro instruction by either the user's program or exit routine. 

Upon entry to the stae retry routine, register contents are as follows: 

• Register 0: 

• Register 1: Address of the work area, as previously described, except that word 
2 now contains the address of the first i/o block and word 26 now contains 
the address of the i/o restore chain. 

• Registers 2-13: Unpredictable. 

• Register 14: Address of an svc 3 instruction. 

• Register 15: Address of the stae retry routine. 

The retry routine should use the freemain macro instruction to free the 104 
bytes of storage occupied by the work area when the storage is no longer needed. 
This storage should be freed from subpool which is the default subpool for 
the freemain macro instruction. 

Again, if the abend/stae interface routine was not able to obtain storage for 
the work area, register contains a 12; register 1, the abend completion code 
upon entry to the stae retry routine; and register 2, the address of the first i/o 
block on the restore chain, or if i/o is not restorable. 

Note: If the program using the STAE macro instruction terminates by the EXIT macro in- 
struction, the EXIT routine cancels all SCBs related to the terminating program. If the 
program terminates by the XCTL macro instruction, the EXIT routine cancels all SCBs related 
to the terminating program except those SCBs that were created with the XCTL=YES option. 
If the program terminates by any other means, the terminating program must reinstate the 
previous SCB by canceling all SCBs related to the terminating program. 



ATTACH— Create a New Task 



This explicit form of attach permits greater flexibility in both the use and the 
result of use of the attach macro instruction. This form of the macro instruction 
differs from the implicit form by the addition of six keyword parameters to those 
described for the implicit form in the OS/VS Supervisor Services and Macros 
publication. Only the added six parameters are shown and explained in this 
description. 

These six parameters can be used only with tasks whose protection key is 
zero. If they are used with other tasks, the default values are used. 



Name 


Operation 


Operands 


[Symbol] 


ATTACH 


■ ■ ■ <JSTCB =fe \ ,SM =fcl SVAREA =/;:;^^l 
(NO f IPROBj 1"^° f 

■^^^ = {pROB } •^'^^•^''^ = {no'} "^^^^ = ^^^^^^^^ 
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Ordinary attach macro instruction parameters. See the description in the 
OS/VS Supervisor Services and Macros pubHcation. 

JSTCB 

Address to be placed in the tcbjstcb field of the tcb of the newly created 
task. The address determines whether the attached task is a new job step 
or a task in the present job step, A new job step is required if the ownership 
of programs is to pass from the attaching to the attached task, that is, if 
you are coding givejpq=yes in the macro instruction. (Also, see the follow- 
ing note.) 

YES-Address of the tcb of the newly created task, that is, this tcb points to 
itself, thus creating a new job step. A new job step is required if owner- 
ship of programs is being transferred from the attaching to the attached 
task, that is, if you are coding givejpq=yes in the macro instruction. 

NO— Address of the tcb of the task using the attach, that is, the attached 
task is to be a task in the present job step. 

,SM 

Operating state of the machine when executing the attached task, 
supv— Supervisor mode. 
PROB— Problem program mode. 

,svarea 

Need for save area. 

YES— A save area is needed for the attaching task. The attach routine will 
obtain a 72 byte save area. If both attaching and attached tasks share 
subpool zero, the save area is obtained there, otherwise it is obtained 
from a new 2K byte block. 

NO— No save area is needed. 

,KEY 

Protection/key of the newly created (attached) task. 

ZERO— Zero. 

PROB— Copy the key from the tcbpkf field of the tcb for the task using the 

ATTACH. 
,GIVEJPQ 

Ownership of programs used by the attaching task. If ownership is to pass 
to the attached task, the attached task must be a new job step, that is, you 
must use jstcb=yes. (Also see the following note.) 
YES— Pass ownership to the newly created task. On completion of the new 

task all programs, both those passed to the new task by the old and 

those acquired by it, are freed. 

NO— Ownership of programs used by the attaching task remain with that 
task; programs acquired by the attached task remain with it. The at- 
tached task shares use of the programs of the attaching task during their 
common existence. At the conclusion of the attached task, the programs 
it acquired are freed; when the attaching task terminates, its programs 
are freed. 

JSCB 

Job step control block address. 
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If specified, that job step control block is used for the new task. If not 
specified, the job step control block of the attaching task is also used for the 
new task. 

Note: If the task to be attached is to be a separate step (JSTCB=YES), ownership of programs 
may be passed ( GIVEJPQ=YES ) or retained ( GIVEJPQ=NO ) . If the newly attached task 
is not to be a separate step (JSTCB=NO), ownership of programs cannot be passed but 
must be retained ( GIVEJPQ=NO ) . The following table summarizes these combinations. 





JSTCB = 1 




YES 


NO 


GIVEPJQ = 


YES 


Valid 


Invalid 


NO 


Valid 


Valid 



JMGL/B— Open or Close SYSJ .IMAGELIB 



The iMGLiB macro instruction is used to open or close sysI.imagelib. When issued 
to open the image library, it is usually followed by a bldl macro instruction and a 
LOAD macro instruction which, respectively, search the library for the image and 
load it into storage. 



Name 


Operation 


Operand 


[symbol ] 


IMGLIB 


OPEN, deb addr 
CLOSE 



OPEN 

Specifies that sysI.imagelib is to be opened and the address of the dcb 
returned in register one. 

CLOSE 

specifies that imagelib is to be closed. 

dcb addr 

is either the address of the imagelib dcb or is a register containing the 
imagelib dcb address. 



QEDIT-Linkage to SVC 34 



The qedit macro instruction generates the required entry parameters and the 
linkage to svc 34 for the following uses: 

• Dechaining and freeing of a cib from the cib chain for a task. 

• Setting a limit for the number of cibs that may be simultaneously chained 
for a task. 
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The format of the qedit macro instruction and an explanation of the operands 
are as follows: 



Name 


Operation 


Operand 


[symbol] 


QEDIT 


ORIGIN = address [, BLOCK = address ] 
[, CIBCTR = number] 



ORIGIN 

The address of the pointer to the first cib on the cm chain for the task. This 
address is obtained using the extract macro instruction. If origin is the only 
parameter specified, the entire cib chain will be freed. 

,BLOCK 

The address of the cib that is to be freed from the cib chain for a task. 

,cibctr 

An integer (from to 255) to be used as a limit for the number of cibs 
to be chained at any one time for a task. 

address 

Any address valid in an rx instruction or one of the general registers (2-12) 
previously loaded with the indicated address. The register must be designated 
by a number or symbol added within the parentheses. 
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EXTRACT— Ptovide Information from TCB Fields 



The EXTRACT macro instruction provides information from specified fields of the 
task control block or a subsidiary control block for either the active task or 
one of its subtasks. The information is placed in an area provided by the 
problem program in the order shown in Figure smi 1. 

The standard form of the extract macro instruction is written as follows. 
Information about the list and execute forms follows this description. 



Name 


Operation 


Operand 


[symbol] 


EXTRACT 


answer area address ",tcb location address 

L'l' J 

,FIELDS= (codes) 



answer area address 

is the address in virtual storage of one or more consecutive fullwords, start- 
ing on a fullword boundary. The number of fullwords required is the same 
as the number of fields specified in the fields operand, unless fields=(all) 
is coded. fields=(all) requires seven fullwords. 
tcb location address 

specifies the address of a fullword on a fullword boundary containing the 
address of a task control block for a subtask of the active task. 

's' indicates that information is requested from the task control block for 
the active task. V is assumed if the operand is omitted or if it is coded to 
specify an address of 0. 
fields= 

is one or more of the following sets of characters, written in any order 
and separated by commas, which are used to request the associated task 
control block information. The information from the requested field is re- 
turned in the relative order shown in Figure smi 1. If the information from 
a field is not requested, the associated fullword is omitted. If all is specified, 
the answer area includes all the fields in Figure smi 1 from grs to tiot, 
including the reserved word. Addresses are always returned in the low-order 
three bytes of the fullword, and the high-order byte is set to 0. Fields for 
which no address or value has been specified in the task control block are 
set to 0. 
ALL— requests information from the grs, frs, reserved, aetx, pri, cmc, and 

tiot fields. 
GRS— the address of the general register save area used by the control pro- 
gram to save the general registers (in the order of through 15) when 

the task is not active. 
FRS— the address of the floating-point register save area used by the control 

program to save the floating-point registers (in the order of 0, 2, 4, 6) 

when the task is not active. 
AETX— the address of the end-of-task exit routine specified in the etxr operand 

of the ATTACH macro instruction used to create the task. 
pri- the current limit (third byte) and dispatching (fourth byte) priorities 

of the task. The two high-order bytes are set to 0. 
CMC— the task completion code. If the task is not complete, the field is set 

to 0. 
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EXTRACT-List Form 



noT— 'the address of the task input/output table. 

COMM— the address of the command scheduler communications list. The list 
consists of a pointer to the communications event control block, and a 
pointer to the command input buffer. The high- order bit of the last pointer 
is set to one to indicate the end of the list. 



Note: You must provide an answer area consisting of contiguous fuUwords, one for each 
of the codes specified in the FIELDS operand, with the exception of the ALL code. If ALL 
is specified, you must provide a 7-word answer area to accommodate the GRS, FRS, 
RESERVED, AETX, PRI, CMC, and TIOT fields. The ALL code does not include COMM. 

For example, if FIELDS=(TIOT,GRS,PRI) is coded, a 3-word answer area is required, 
and the extracted information appears in the answer area in the same relative order as shown 
in Figure SMI 1. (That is, GRS is returned in the first word, PRI in the second word, 
TIOT in the third word.) 



answer area address 












GRS 




ADDRESS 


FRS 




ADDRESS 




Reserved (set to zero) 


AETX 




ADDRESS 


PRI 






VALUE 


VALUE 


CMC 




COMPLETION CODE 


TIOT 




ADDRESS 


COMM 




ADDRESS 




J A 1-..^ . 1 










1 



Figure SMI 1. Field Order for the EXTRACT Answer Area 



The list form of the extra.ct macro instruction is used to construct a control 
program parameter list. 



The description of the standard form of the extract macro instruction explains 
the function of each operand. The description of the standard form also indicates 
which operands are totally optional and which are required in at least one of 
the pair of list and execute forms. The format description below indicates the 
optional and required operands in the list form only. 
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EXTRACT-Execute Form 



Name 


Operation 


Operand 


[symbol] 


EXTRACT 


[answer area address] J tcb location address ) 

L i's: u 

[,FIELDS = (codes)],MF=L 



symbol 

is any symbol valid in assembler language. 

address 

is any address that may be written in an A-type address constant. 



codes 



are one or more of the sets of characters defined in the description of 
the standard form of the macro instruction, Each use of the fields operand 
in the execute form overrides any previous codes. 



MF=:L 

indicates the list form of the extract macro instruction. 



A remote control program parameter list is referred to, and can be modified by, 
the execute form of the extract macro instruction. 

The description of the standard form of the extract macro instruction explains 
the function of each operand. The description of the standard form also indicates 
which operands are always optional and which are required in at least one of 
the pair of list and execute forms. The following format description indicates 
the optional and required operands in the execute form only. 



Name 



Operation 



Operand 



[symbol] 



EXTRACT 



[answer area address] 



[i-s.' 



b location address 







[,FI ELDS= (codes)] ,MF=/E, ( control program list 
I < address 

\ Ml) 



symbol 

is any symbol valid in assembler language. 
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address 

is any address that is valid in an KX-type instruction, or one of general 
registers 2 through 12, previously loaded with the indicated address. The 
register may be designated symbolically or with an absolute expression, and 
is always coded within parentheses. 

codes 

are one or more of the sets of characters defined in the the description 
of the standard form of the macro instruction. Any previous field operands 
are canceled and must be respecified if required for this execution of ex- 
tract. 



MF= 



E, 



control program list address 

(1) 

indicates the execute form of the macro instruction using a remote control 
program parameter list. The address of the control program parameter list 
can be coded as described under "address" or can be loaded into register 1, 
in which case code mf=(e, (1)). 



WTO /WTOR— Write to Operator 



WTO — Standard Form 



A special operand allows key-0 users to route messages to remote work stations. 
The user must specify the queue identification number of the remote station. 

The format of the standard form of the wto macro is: 



Name 



Operation 



Operands 



[symbol] 



WTO 



let 



) 



message 

text'[,line type] ),... 
[,ROUTCDE = (number [.number. 
[,DESC=(number[,number...] )] 
N 

MSGTYP-< JOBNAMES, 

STATUS 

ACTIVE 
[,MCSFLAG-(name[,name...] )] 
[,QID=nnnnn] 



Only the two operands described here are required for res support. The use of 
all the other operands is explained in OS/VS Supervisor Services and Macro 
Instructions, GC27-6979. 

'message' 

is the text of the message to be sent to the res work station. The maximum 
length is 125 characters. The text may contain any characters that can be 
used in a c-type dc instruction. 

QiD=:nnmin 

is the decimal queue identification number of the remote user who is to 
receive the message. If the qid is not equal to zero, only the indicated remote 
station will receive the wto(r) . If the qid equals zero, normal routing is used. 
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Specification or this parameter causes the macro to generate the msgtyp 
field and to place the binary qm immediately following msgtyp. Byte 0, bit 
3 in MSGTYP is set on ( set to 1 ) to indicate that a qid is present. Byte 0, bit 3 
of MCSFLAG is sct On to indicate that the msgtyp field exists. 



v/TO produces the following return codes 

Return Code 
'00' 
X'04' 



X'08' 

X'OC 
X'lO' 

X'14' 

X'80' 

X'84' 
X'88' 
X'8C' 
X'90' 



Meaning 

No errors 

Number of lines in parameter list is zero or greater than ten. If 
zero, request ignored. If greater than ten, only ten are printed. 

Passed message id cannot be matched with any existing unended 
MLWTO chain. Request ignored. 

Invalid line type encountered. Message terminated at that point. 

Request had routing code of 11 (WTP). Not allowed for MLWTO. 
Request ignored. 

In MLWTO request, queue to hardcopy only bit on in the 
MCSFLAG field. Request ignored. 

Unauthorized user of remote WTO(R) (not supervisor or key-0 
user). Request ignored. 

QID invalid ( too large ) . Request ignored. 

Receiver not logged on. Request ignored. 

RTAM unable to find space. Request ignored. 

RTAM unable to queue message. Request ignored. 



WtO — list Form 



1 he format of the list torm ot wto is : 



Name 



Operation 



Operands 



[symbol] 



WTO 



{('text'[,line type] ),...) 
'message' j 

[,ROUTCDE=(number[,number...] )] 
[,DESC=(number[,number...] )] 



N 

,MSGTYP=< JOBNAMES 
STATUS 
ACTIVE 
[,IVICSFLAG={name[,name...] )] 




The QID operand is required for res support. 



Qmz= 



rinnnn — is the decimal queue identification nmnber of the remote user who 
is to receive the message. 

Y — indicates that the 2-byte qm field should be generated and set to X'OOOO'. 

N — indicates that the qid field should not be generated. 
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WTO — Execute Form 



The execute form of the wto macro is: 



Name 


Operation 


Operands 


symbol 


WTO 


/^ (control program list address)) 

[,010= ff^rll 



The QiD operand is required for res support. 

QID= 

address — specifies the address of the 2-byte binary qid. The macro moves 
the QID from the specified location to the qid field in the parameter list. 

(reg) — specifies the register containing the address of the 2-byte binary qid. 
The macro moves the qm to the qid field in the parameter list. 



WTOR — Standard Form 



The format of the standard form of the wtor macro is : 



Name 


Operation 


Operands 


[symbol] 


WTOR 


'message', reply address, length of reply 
,ecb address 

[.ROUTCDE={number [.number...] )] 
[,DESC=(number [.number...])] 

r ^nm 

,MSGTYP= Jy' 
[,MCSFLAG=(name [,name...])] 






[,QID=nnnnn] 



Only the operands described here are required for res support. The use of the 
other operands is explained in OS/VS Supervisor Services and Macro Instructions, 
GC27-6979. 

'message' 

is the text of the message to be sent to the res work station. The maximum 

o 

length is 125 characters. The text may contain any characters valid in a 
c-type DC instruction. 

reply address 

is the virtual address of the area into which the reply is to be placed. 
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length of reply 

is the length of the reply message ( minimum of one byte ) . 

ecb address 

is the address of the ecb (event control block) to be used to indicate 
completion of the reply. 

QiD^^nnnnn 

is the decimal queue identification number of the remote user who is to 
receive the message. If the qid is not equal to zero, only the indicated remote ■ 
station will receive the wto(r). If the qid equals zero, normal routing is used 

Specification of this parameter causes the macro to generate the msgtvi 
field and to place the binary qid immediately following msgtyp. Byte 
bit 3 in msgtyp is set on (set to one) to indicate that a qid is presenl 
Byte 0, bit 3 of mcsflag is set on to indicate that the msgtyp field exists 

WTOR produces the following return codes : 



'00' 
'80' 

'84' 
'88' 
'8C' 
'90' 



No errors 

Unautliorized issuer of remote WTO(R)- 

not supervisor of lcey-0 user 

QID invalid — too large 

Receiver not logged on 

RTAM unable to find space 

RTAM unable to queue message 



WTOR — List Form 



The list form of wtor is: 



Name 


Operation 


Operands 


symbol 


WTOR 


'message', [reply address] 

, [length of reply] , [ecb address] 

,MF=L [,R0UTCDE= (number [,number...] )] 

[,DESC= (number [.number...] )] 

r ^nh 

,msgtyp= yJ 

[,MCSFLAG= (name [,name...])] 
r /■nnnnn"^"! 



The qid operand is required for res support. 

QID— 

nnnnn — is the decimal queue identification number of the remote user who 
is to receive the message. 

r — indicates that the 2-byte qid field should be generated and set to X'OOOO'. 

N — indicates that the qid should not be generated. 
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WTOR — Execute Form 



The execute form of the wtor macro is: 



Name 


Operation 


Operands 


[symbol] 


WTOR 


.[reply address] , [length of reply] 
,[ecb address] 

P /p C control program list addressM 
' ^ ' j(1) \ 

raiD= if^rn 

L treg) )J 



The QiD operand is required for res support. 

QID=: 

address — specifies the address of the 2-byte binary qid. The macro moves 
the QID from the specified location to the qid field in the parameter list. 

( reg ) — specifies the register containing the address of the 2-byte binary qid. 
The macro moves the qid to the qid field in the parameter list. 
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Adding SVC Routines to the Control Program 



This section provides detailed information on how to 
write an svc routine and insert it into the control pro- 
gram portion of vsl. 

Documentation of the internal logic of the super- 
visor and its relationship to the remainder of the con- 
trol program can be obtained through your ibm Branch 
Office. 



Section Outline 
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Writing SVC Routines 



Because your svc routine will be a part of the control program, you must follow 
the same programming conventions used in svc routines supplied with vsl. 

Four types of svc routines are supplied with vsl and the programming con- 
ventions for each type differ. The general characteristics of the four types are 
described in the following text, and the programming conventions for all types 
are shown in tabular form. 



Characteristics of SVC 
Routines 



All svc routines operate in the supervisor state. You should keep the following 
characteristics in mind when deciding what type of svc routine to write: 



Location of the routine— Yom svc routine can be either in virtual storage at 
all times as part of the resident control program, or on a direct access device 
as part of the svc library. Types 1 and 2 svc routines are part of the resident 
control program, and types 3 and 4 are in the svc library. 

Size of the routine— Types 1, 2, and 4 svc routines are not limited in size. 
However, you must divide a type 4 svc routine into load modules of 2048 
bytes or less. The size of a type 3 svc routine must not exceed 2048 bytes. 

Design of the routine— Type 1 svc routines must be reenterable or serially 
reusable; all other types must be reenterable. If you wish to aid system facilities 
in recovering from machine malfunctions, your svc routines should be 
refreshable. 

Interruption of the routine— Yvhen your svc routine receives control, the cfu 
is masked for all maskable interruptions but the machine check interruption. 
All type 1 svc routines must execute in this masked state. If you want to 
allow interruptions to occur during the execution of a type 2, 3, or 4 svc 
routine, you must change the appropriate masks. If you expect that a type 
2, 3, or 4 svc routine will run for an extended period of time, it is recommended 
that you allow interruptions to be processed where possible. 



Programming Conventions 
for SVC Routines 



The programming conventions for the four types of svc routines are summarized 
in Figure svc 1. Details about many of the conventions are in the reference notes 
that follow the table. The notes are referred to by the numbers in the last 
column of the table. If a reference note for a convention does not pertain to 
all types of svc routines, an asterisk indicates the types to which the note refers. 
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Conventions 


Typel 


Type 2 


Type 3 


Type 4 


Reference 
Code 


Part of resident control 
program 


Yes 


Yes 


No 


No 




Size of routine 


Any 


Any 


12048 
bytes 


Each load 
module 
< 2048 
bytes 




Reenterable routine 


Optional, 
but must 
be serially 
reusable 


Yes 


Yes 


Yes 


1 


May allow interruptions 


No 


Yes 


Yes 


Yes 


2 


Entry point 


Must be the first byte of the routine or load 
module, and must be on a doubleword boundary 




Number of routine 


Numbers assigned to your SVC routines should 
be in descending order from 255 through 200 




Name of routine 


IGCnnn 


IGCnnn 


IGCOOnnn 


IGCssnnn 


3 


Register contents at entry 
time 


Registers 3, 4, 5, and 14 contain communication 
pointers; registers 0, 1, and 15 are parameter 
registers 


4 


May contain relocatable 
data 


Yes 


Yes 


No* 


No* 


5 


Can supervisor request 
block (SVRB) be extended 


Not 
applicable 


Yes* 


Yes* 


Yes* 


6 


May issue WAIT macro 
instruction 


No 


Yes* 


Yes* 


Yes* 


7 


May issue XCTL macro 
instruction 


No 


No 


No 


Yes* 


8 


May pass control to what 
other types of SVC 
routines 


None 


Any 


Any 


Any 




Type of linkage with other 
SVC routines 


Not 
Applicable 


Issue supervisor call (SVC) instruc- 
tion 




Exit from SVC routine 


Branch using return register 14 




Method of abnormal 
termination 


Use resi- 
dent ab- 
normal 
termination 
routine 


Use ABEND macro instruction or 
resident abnormal termination 
routine 


9 



Figure SVC 1. Programming Conventions for SVC Routines 
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Reference SVC Routine 
Code Types Reference Notes 

1 all If your svc routine is to be reenterable, you cannot 

use macro instructions whose expansions store in- 
formation into an inline parameter list. 

2 all Write svc routines so that program interruptions 

cannot occur. If a program interruption does occur 
during execution of an svc routine, the routine 
loses control and the task that called the routine 
terminates. 

If a program interruption occurs and you are 
modifying a serially reusable svc routine, a system 
queue, control blocks, etc., the modification vv^ill 
never complete; the next time the partially modified 
code is used, the results w^ill be unpredictable. 

3 all You must use the following conventions when 

naming svc routines: 

• Types 1 and 2 must be named IGCnnn; nnn is 
the decimal number of the svc routine. You must 
specify this name in an entey, csect, or start 
instruction. 

• Type 3 must be named IGCOOnnn; nnn is the 
signed decimal number of the svc routine. This 
name must be the name of a member of a parti- 
tioned data set. 

• Type 4 must be named IGCssnnn; nnn is the 
signed decimal number of the svc routine, and 
ss is the number of the load module minus one. 
For example, ss is 01 for the second load module 
of the routine. This name must be the name 
of a member of a partitioned data set. 

4 all Before your svc routine receives control, the con- 

tents of all registers are saved. For type 4 routines, 
this applies only to the first load module of the 
routine. 

In general, the location of the register save area 
is unknown to the routine that is called. When 
your svc routine receives control, the status of the 
registers is as follows: 

• Registers and 1 contain the same information 
as when the svc routine was called. 

• Register 2 contains unpredictable information. 

• Register 3 contains the starting address of the 
communication vector table. 
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Reference 
Code 



SVC Routine 
Types 



Reference Notes 



• Register 4 contains the address of the task con- 
trol block (tcb) of the task that called the svc 
routine. 

• Register 5 contains the address of the super- 
visor request block (svrb), if a type 2, 3, or 4 
SVC routine is in control. If a type 1 svc routine 
is in control, register 5 contains the address of 
the last active request block. 

• Registers 6 through 12 contain unpredictable 
information. 

• Register 13 contains the same information as 
when the svc routine was called. 

• Register 14 contains the return address. 

• Register 15 contains the same information as 
when the svc routine was called. 

You must use registers 0, 1, and 15 if you want 
to pass information to the calling program. The 
contents of registers 2 through 14 are restored 
when control is returned to the calling program. 



3,4 Because relocatable address constants are not re- 

located when a type 3 or 4 svc routine is loaded 
into virtual storage, you cannot use them in coding 
these routines; nor can you use macro instructions 
whose expansions contain relocatable address con- 
stants. Types 1 and 2 are not affected by this re- 
striction since they are part of the resident control 
program. 



2,3,4 You can extend the svrb, in 8-byte increments, from 

96 bytes up to 144 bytes. The extended area is 
available as a work area during execution of your 
routine only if you specify the extension during 
the system generation process. When your svc 
routine receives control, register 5 contains the ad- 
dress of the SVRB to which the extended save area 
is appended. 



2,3,4 You cannot issue the wait macro instruction unless 

you have changed the system mask to allow i/o 
and external interruptions. If you have allowed 
these interruptions, you can issue wait macro in- 
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Reference SVC Routine 
Code Types Reference Notes 



structions that await either single or multiple events. 
The event control block (ecb) for single-event waits 
or the ECB list and ecbs for multiple-event waits 
must be in pageable storage. 



When you issue an xctl macro instruction in a 
routine under control of a type 4 svrb, the new load 
module is brought into a transient area. 

The contents of registers 2 through 13 are un- 
changed when control is passed to the load module; 
register 15 contains the entry point of the called 
load module. 



all Type 1 svc routines must use the resident abnormal 

termination routine to terminate any task. The 
entry point to the abnormal termination routine is 
in the communication vector table (cvt). The sym- 
bolic name of the entry point is cvtbterm= 

Types 2, 3, and 4 svc routines must use the abend 
macro instruction to terminate the current task, and 
must use the resident abnormal termination routine 
to terminate a task other than the current task. 

Before the resident abnormal termination routine 
is entered, the cpu must be masked for all maskable 
interni^^tions but the machine check interruption 
and registers 0, 1, and 14 must contain the follow- 
ing: 

• Register contains the address of the tcb of the 
task to be terminated. 

• Register 1 contains the following information: 
Bit is a 1 if you want a dump taken. 

Bit 1 is a 1 if you want to terminate a job step. 

Bits 2-7 are zero. 

Bits 8-19 contain the error code. 

Bits 20-31 are zero. 

• Register 14 contains the return address. The 
resident abnormal termination routine exits by 
branching to the address contained in register 
14. 

The contents of register 15 are destroyed by the 
abnormal termination routine. 
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Inserting SVC Routines into the Control Program 



You insert svc routines into the control program during the system generation 
process. 

Before your svc routine can be inserted into the control program, the routine 
must be a member of a cataloged partitioned data set. You must name this data 
set SYsl.name, where the name is a name of your choice. 

The following text gives a description of the information you must supply 
during the system generation process. You will find a description of the macro 
instructions required during the system generation process in the VSl SYSGEN 
publication. 



Specifying SVC Routines 



You use the svctable macro instruction to specify the svc number, the type of 
svc routine, and, for type 2, 3, or 4 routines, the number of double words in the 
extended save area. 



inserting SVC Routines 
During the System Genera- 
tion Process 



To insert a type 1 or 2 svc routine into the resident control program, use the 
RESMODS macro instruction. You must specify the name of the partitioned data 
set and the names of the members to be inserted into the control program. Each 
member can contain more than one svc routine. 

To insert a type 3 or 4 svc routine into the svc hbrary, use the svclib macro 
instruction. You must specify the name of the partitioned data set and the names 
of members to be included in the svc library. The member names must conform 
to the conventions for naming type 3 and 4 routines; that is, IGCOOnnn and 
IGCssnnn. 
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How to Use the Traemg Routine 



This section describes the function of the tracing 
routine, and provides a detailed description of the in- 
formation made available by the tracing routine. 



Section Outline 
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The tracing routine is a vsl feature which you can use as a debugging and 
maintenance aid. The tracing routine stores, in a table, information pertaining 
to the following conditions: 

• sio instruction execution. 

• SVC interruption. 

• i/o interruption. 

• Dispatching interruption. 

You can include the tracing routine and its table in the control program during 
the system generation process. This is done using the trace option in the 
CTKLPROG macro instruction. The format of this option requires you to supply 
the number of entries in the table. Each table entry can contain information 
relating to one of the traced conditions. When the last entry in the table is filled, 
the next entry will overlay the first. 



Table Entry Formats Table entry formats are as follows: 



I/O 
Interrupt 




X'8' X'10' 


X'12' 




l/OoldPSW 


Channel Status Word 


2cuu 


SIO 


SIO 
cc 


Device 
Address 


CAW 


Channel Status Word 


30xx 


SVC 


SVC old PSW 


Reg 


Regl 


OOSVC# 


Dispatch 


New PSW 


NewTCB 


Old TCB 


lOxx 




XX represents meaningless information. 

SIO cc is the Start I/O condition code. 

For a Start I/O CSW to be valid, SIO cc must be one, otherwise 
the CSW contents are meaningless. 



Location of the Table 



The addresses of the last entry made in the table, the beginning of the table, and 
the end of the table are contained in a 12-byte field. The address of this field is 
contained in the fuUword starting at location 20. The format of the field is as 
follows: 








31 





31 







31 1 


Address 
of the Last Entry 


Address 
of the Table Beginning 


Address 
of the Table End 



If requested through the sdata operand of the snap macro, the dump lists the 
SIO, SVC, i/o, and dispatching interruptions table entries, starting with the oldest, 
A number is assigned to each entry and the oldest entry is 0001. 
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The Time Slicing Facility 



This section describes the time sHcing facility, a sys- 
tem generation option available with vsl. Use of this 
facility allows the grouping of tasks of equal priority 
or partitions into a time-slice group so that each 
task within the group is limited to a fixed interval of 
CPU time each time it is given control. The facility is 
included in the system mainly to provide a method 
of controlling response time of a task. 

Included in the section are a description of the 
faciHty, how it fits into the system, and the applications 
for which it is most effective. It also describes the 
prerequisite actions that must be taken, the use of 
the time slicing facility, and its operating charac- 
teristics. 
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The Time Slicing Facility 



The time slicing facility allows the user to establish a group of tasks (called 
the time-shce group ) or partitions that are to share the use of the cpu, each for 
the same, fixed interval of time. When a member of the time-slice group has 
been active for the fixed interval of time, it is interrupted and control is given 
to another member of the group, which will, in turn, have control of the cpu 
for the same length of time. In this way, all member tasks are given an equal 
sHce of CPU time, and no task or partition within the group can monopolize the 

CPU. 

In vsl, only partitions that are assigned to the time-slice group will be time- 
sliced, and they are time sliced only when the first partition in the group is the 
highest-priority ready task. Dispatching of the partitions continues within the 
group until all the partitions are in a waiting state, or until a partition with a 
higher priority is in a ready state. 

The group of tasks to be time sliced (selected by priority or partition range) 
and the length of the time shce are specified by the installation at system genera- 
tion time. This can be modified in vsl through the define command. Any task 
or partition in the system that is not defined within the time-slice group is dis- 
patched under the current priority structure; that is, the task or partition is 
dispatched only when it is the highest priority ready task or partition on the tcb 
queue. 



System Configuration and 
System Relationships 



The time slicing facihty can be used with any vsl configuration. The time slicing 
facihty is especially useful in a graphics environment or in any application of a 
conversational nature where concurrent tasks may involve conversation between 
the user and the problem program through a terminal. Establishing a time-slice 
group within this environment enables those tasks to be performed with a uni- 
form response time. 



Prerequisite Actions 



Time slicing is specified in the tmslice parameter of the ctklprog system genera- 
tion macro instruction. The group(s) of tasks or partitions to be time sliced and 
the length of the time slice are specified in this parameter. 

In vsl, a group of contiguous partitions defines the time-slice group. All tasks 
scheduled into those partitions are time sliced and are treated as though they 
had the same dispatching priority. Only one group of tasks can be specified to be 
time sliced. For example, a time-slice group for vsl might be specified during 
system generation, as follows: 



CTRLPROG 



TMSLICE = {P4 - P6, SLC - 256) 



In this example, partitions P4, P5, and P6 make up the time-slice group and 
are assigned a time slice of 256 milliseconds for each and every task executing 
in these partitions. 
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System Initialization Time 



If time slicing has been selected during system generation, the group of tasks 
to be time sHced and the length of the time slice can be modified during system 
initialization. In vsl, modifications to the time-sHcing specifications are made 
in much the same way as other partition modifications. At system initialization, 
changes can be indicated by replying 'yes' to the message: 'ieeSOId change 
PABTiTiONS?'. After system initialization, changes can be indicated through 
the DEFINE command. In both cases, changes are actually made by responding 
to the message: 'iee002a enter definition' or 'iee803a continue definition' with 
the new tmsl reply. With this reply, the operator can request a list of current 
time-slicing specifications, change the range of time-slicing partions and the time 
interval, or cancel time-slicing specifications altogether. 



How to Invoke the Time 
Slice Facility 



Time slicing is invoked through either the job statement or through the use of 
the ATTACH and chap macro instructions. 

If a task is part of the time slice group because its jobclass is assigned to 
a time slice partition, the task gains control according to the position of the 
time slice partition with respect to other partitions. 

If a task becomes part of the time slice group through the use of attach or 
chap, the task gains control according to the priority used v^dth attach or chap. 
The task gains control, as part of the time sHce group, when the partition with the 
same priority gains control (even though the task resides in a partition that is 
not part of the time-slice group). Equally, a task that is time sliced may use 
attach or CHAP with a priority that does not fall within the range of priorities 
assigned to the time-slice group. The attached or changed task is not part of 
the time-slice group even though it resides in a time slice partition. 



Time Slicing's Effect on the 
ATTACH and CHAP 
Macro Instructions 



New tasks can be introduced into a time-slice group through the use of the 
ATTACH and CHAP macro instructions, when the attaching or new priority selected 
is equal to that of a time-slice group. These new tasks conform to all the rules 
for time slicing. 

The CHAP macro instruction may remove a task from a time-shce group. If it 
does, this terminates all that task's time-slice characteristics. The attach macro 
instruction may create a task that is not a member of a time-slice group, even 
though the originating task was. 



Using the Time Slice Facility 



The time-slice group is composed of a group of contiguous partitions and all tasks 
scheduled into those partitions are time sliced. Also, each partition in the system 
is assigned to at least one job class. Since a job is scheduled into a partition 
according to the class parameter on the job statement, careful consideration 
should be given to the job-class assignment in order to enable the user to control 
the use of time sHcing at his installation. For example, 

1. Partitions P0-P2 have been assigned as the time-sHce partitions 

2. The partitions have been assigned the following job classes: 

PO=G, P1=G, P2=(G,D), P3=B, P4=(B,C,D) 
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In this example, the user can ensure that a job will be time sliced by specifying 
CLAss=G on the job statement. This specification guarantees that the scheduler 
will initiate the job only into a partition assigned to class g, that is, PO, Pi, 
or P2. Since P0-P2 have been designated as time-slice partitions, that job will 
be time sliced. 

CAUTION 

Note that if the class parameter of a job was D, the job may or may 
not be time sliced, depending on whether it is initiated into partition P2 or P4. 
See the appropriate Message Library pubHcation (message ieeSOSa) for in- 
formation on warning the operator about such situations. 

Time sHcing is assigned both by partition ( as shown ) and by dispatch priority 
of the jobclasses assigned to the time slice partitions. If a program uses the 
ATTACH or chap macro instruction, the priority used with attach or chap de- 
termines whether the attached or changed task is time sliced, not the partition 
in which it resides. (However, a program cannot exceed the limit priority 
assigned its jobclass.) See the Supervisor Services and Macros publication for a 
discussion of dispatch and limit priority. 



Operating Characteristics The time-slicing mechanism operates within the structure of the current dis- 

patcher. A priority is assigned to a group of tasks that are to be time sliced. The 
time slicing occurs among the tasks in the group only when the priority level of 
the group is the highest priority level that has a ready task. Each task or parti- 
tion in the group is dispatched for the specified time slice. The time slicing con- 
tinues until either all tasks or partitions are waiting, or a task or partition of 
higher priority than that of the group becomes ready. 

The dispatcher will recognize that a priority level is one that is being time 
sliced; it will determine which task or partition within the group is to be dis- 
patched and then dispatch that task or partition for the maximum time interval. 
If the time slice task loses control prior to the expiration of its interval (because 
an implicit or explicit wait is issued, or because a higher priority task or partition 
becomes ready), the remainder of the time is not saved. That is, when control 
returns to the time-slice group, the next ready task or partition in the group is 
given control, not the interrupted task or partition. 



Effect of System Tasks on The time slicing option is included in the system mainly to provide a method 
Time-Slice Groups of controlling response time of a task. However, since it is being implemented 

in a priority dispatcher, any task of a higher priority than that of the time-slice 
group will be dispatched first, if it is ready. Note also that the time-slicing 
mechanism applies only to the problem program priorities, 0-13. Priorities 14 
and 15 are reserved for the system and cannot be time sliced. Therefore, the 
response time of a time-sHce task can be affected by the processing of system 
tasks, such as readers, writers, master scheduler, etc., which will always run 
at a higher priority than the time-shce group. Therefore, to guarantee response 
time, the time slice group should be defined in the high priority partitions. 

Non-interactive jobs should not be run concurrently and time sliced since this 
may significantly decrease performance. 
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Writing System Output Writer Routines 



This section provides guidelines for writing your own 
output writer routines for your vsl operating system. 
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Wrifing System Output Writer Routines 



Output Writer Functions 



When a job is executing, system messages and data sets specifying the sysout 
parameter (for example, in the dd statement) are recorded on direct access de- 
vices, unless the job falls into a job class assigned to a direct sysout writer. In 
that case, both messages and data addressed to a sysout data set are written 
directly to the device for the direct sysout writer for that job class. (Messages 
for jobs canceled on the input queue and jobs failed by the reader, and data 
produced by system tasks cannot be processed by direct system output writers.) 

When the job completes (assimiing it doesn't use a direct sysout writer), 
entries are made in system output class queues that represent the data sets and 
messages directed to the output classes. Later, system output writers remove these 
entries from the queues and process the data they represent. Processing consists 
of transcribing system messages and data sets to the output device. The data set 
writer routine used for a data set may be specified by name in a dd statement, 
otherwise, a standard iBM-supplied writer routine is used. The standard routine 
transcribes the data set to the specified output device, making only those data 
format and control character transformations required to conform to the attributes 
specified for the output data set. 

The following material describes how you may write a nonstandard data set 
writer routine. 

Note: User-written output writer routines are not supported to RTAM devices. 



Before writing or modifying an output writer routine, you should be familiar with 
the functions performed by the standard data set writer for vsl. (For the re- 
mainder of this section the vsl data set writer is referred to as the standard 
writer.) In general, these functions include opening the data set (referred to as 
an input data set) that contains the processed information, obtaining the records 
of the data set, checkpointing the data set if requested, making any necessary 
transformations in record format or control character attributes, and placing these 
(possibly transformed) records in the output data set, which appears on a 
specified output device. The standard writer also must close the input data set 
and restore system conditions to the state they were in before the writer routine 
was invoked. The standard writer in vsl is attached (by the attach macro 
instruction) at start time and no longer uses a subtask for normal data set 
processing. 



Conventions to be Followed 



To use your own output writer routine, you must specify the name of your 
routine as a parameter in the sysout operand of a dd statement (see the Job 
Control Language publication). (This parameter is ignored if the job falls into 
a jobclass assigned to a direct sysout writer. ) Your routine must be in the system 
library (sysLunkiib). A writer routine is not limited in size except that size may 
influence the partition requirements of the system output vmter (see title OS/VSl 
Storage Estimates publication). 
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ByteO 



Bytes 1 -3 
Bytes 4-7 
Bytes 8-11 

Bytes 12-15 



Output Device Indicator. 

Bit (High-order bit): If this bit is on (set to 1 ), the output 

unit is a 1442 punch. 
Bit 1 If this bit is on, the output unit is either a punch or a 

tape with a punch as the ultinnate destination. 
Bit 2 If this bit is on, the output unit is either a printer or a 

punch. 
Bits 3-7 No significant information. 

Not used (i.e., do not contain information significant to data set 
writers, but must be left intact.) 

This word contains the address of the data control block (DCB) for 
the opened output data set to be referred to by the writer. 

This word contains the DCB address for the input data set from 
which your writer will obtain logical records. (At the time this 1 2 - 
byte parameter list is given to your writer, the input data set is not 
open.) 

Pointer to the CANCEL ECB for this writer. The ECB will be posted 
by the CANCEL command, and the user writer may take any 
desired action. 



Figure WWT 1. Parameter List Referred to by Register 1 



Your routine is attached (by the attach macro instruction) when a data set 
requiring the routine is to be processed. The standard linkage conventions for 
attaching are used. Any storage required for work areas and tables should be 
obtained by the getmain macro instruction and released by the freemain macro 
instruction. Your output writer routines must be reenterable. 

When your routine is finished, it must return control to the standard writer by 
using the return macro instruction. 

After job management routines perform initialization requirements and open 
the output data set into which your writer routine will put records, control is 
given to your routine by the attach macro instruction. At this time, general 
registers 1 and 13 contain information that your program must use. Register 1 
contains the storage address of a 16-byte list. Figure ^vwT 1 describes the infor- 
mation in this parameter list. Your writer should check the cancel ecb that is 
passed in the parameter list if the writer is to be cancelable. 

The switches indicated by the three high-order bit settings in byte should be 
used to translate control character information from the input data set records to 
the form required by the output data set records. Based on the indications given 
in Figure wwt 1, the high-order three bits of byte signify the type of output 
device as follows: 

111 1442 punch unit 

Oil 2520 punch unit or 2540 punch unit 

001 1403 printer, 1443 printer, or 3211 printer unit 

010 tape unit with ultimate punch destination 

000 ..... tape unit with ultimate printer destination 
Wh©Q your writer gets control, it must preserve the contents of registers 
through 12, and 14. Register 13 contains the address of a standard register save 
area where you are to save the contents of these registers. You can save the 
contents of register 13 by using the save macro instruction. 

An output writer routine must issue an open macro instruction to open the 
desired input data set residing on a direct access device as a result of tiie 
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previous execution of a processing program. (Note: The output data set used by 
a writer is opened by a job management routine before control is given to the 
writer. This output data set must be given records by a put macro instruction 
operating in the 'locate' mode. The OS/VS Data Management Macro Instructions 
publication describes this macro instruction. ) 

Your data set writer must provide a synad routine to process errors associated 
with the output as well as the input data set. 

Before the open macro instruction is issued, the dcbd macro instruction can be 
used to symbolically define the fields of the dcb, and the exlist and/or synad 
routine addresses can be inserted. Other than synad, no modifications can be 
made to the output dcb. 

After your routine finishes writing the output data set, it must close the input 
data set and return using the return macro instruction. A return code must be 
placed in register 15. This code should indicate that an unrecoverable output 
error either has occurred (code of 8) or has not occurred (code of 0). 



General Processing Performed by Standard Output Writer 



This section provides a general description of the procedures followed by the 
standard writer. If you write your own writer routine, you may wish to delete, 
modify, or add to some of these procedures, depending on the characteristics of 
your data set(s). However, your procedures must be consistent with operating 
system conventions. 

SAVING REGISTER CONTENTS 

Upon entering the writer program, your program must save the contents of the 
general registers, as previously discussed. 

OBTAINING STORAGE FOR WORK AREAS 

In this work area, switches are established, record lengths and control characters 
are saved, and space is reserved for other uses. You should obtain storage by 
a GETMAIN macro instruction. 

PROCESSING INPUT DATA SEt(s) 

To process a data set, the writer must get each record individually from the input 
data set, transform (if necessary) the record format and the control characters 
associated with the record in accordance with the output data set requirements, 
and put the record in the output data set. Data set processing by the standard 
writer can be considered in three aspects. 
1. The first consideration is what must be done before actually obtaining rec- 
ords from an input data set. If the output device is a printer, provision must 
be made to handle the two forms of record control character that may accom- 
pany a record in an output data set. The printer is designed so that if the 
output data set records contain machine control characters, a record (line) 
is printed before the eJBFect of its control character is considered. However, if 
ANSI control characters are used in the output data set records, the control 
character efiFect is considered before the printer prints a record. See Control 
Character Transformations. 

Thus, if all the input data sets do not have the same type of control char- 
acters, it may be desirable to avoid overprinting of the last Hne of one data 
set with the first line of the following data set. If the records of the input 
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data set have machine control characters (mcc) and the output data set 
records are to have ansi control characters (ace), the standard writer pro- 
duces a control character that indicates one hne should be skipped before 
printing the first hne of output data. 

If the input data set records have ace and the output data set records are 
to be written with mcc, the standard writer prints a line of blanks before 
printing the first actual output data set record. Following this line of blanks, 
a one-hne space is generated before the first output record is printed. The 
preceding printer initialization procedure (or a similar one based on the 
characteristics of your data sets) is recommended. 

2. After an input data set is properly opened and any necessary printer initiali- 
zation is completed, the writer obtains records from the input data set. 
The standard writer uses a unique interface to the spool manager to open, 
close, and obtain each input record. As each record is obtained, its control 
character must be adjusted, if necessary, to agree with that required for 
output. If a control character is added to the input record, it is placed to the 
left of the first byte of data. The standard writer receives only undefined 
format records from the spool manager and passes them to the jES-oriented 
access method (jam). The record format specified for the output data set 
is ignored for unit record devices. For a tape output device, the correct 
format is constructed by jam before the record is written. For fixed-length 
record output, the length of the records in the output data set is obtained from 
the DCBLRECL field of the dcb. If an input record length is greater than the 
length specified for the records of the output data set, the necessary right- 
hand bytes of the input record are truncated. If the input record length is 
smaller than the output record length, jam left-justifies the input record and 
adds blanks on the right end to give the correct length. 

When the output record length is variable and the input record length is 
fixed, JAM constructs each output record by adding variable record control 
information to the output record. The record control information is four bytes 
long and is added to the left end of the record. If the output record is not 
at least 18 bytes long, it is further modified by padding bytes (blanks) added 
to the right end of the record. If the output record length does not agree with 
the length of the output buflFer, jam makes the proper adjustment. 

Note: 

The input and output interfaces utilized by the standard writer are not available to 
user writer routines. The writer constructs the normal qsam interface before attaching 
the user routine. Since the output data set is previously opened, a user writer routine 
must adhere to the established conventions. The output data set is opened to receive 
records from the put macro instruction operating in the locate mode. It is the respon- 
sibility of the user's routine to verify that correct control characters and record formats 
are passed to qsam. 

The input dcb for the user routine is initialized to use the get macro in locate mode. 
This can be overridden before open, if desired. 

3. The third aspect to consider is an end-of-input data set routine. The stand- 
ard writer handles output to either a card punch unit or a printer unit, as 
required. Output to an intermediate device such as a tape unit is considered 
in light of the ultimate destination (for example, punch or printer). If proper 
consideration is not given, all records from a given data set may not be avail- 
able on the output device until the output of records from the next data set 
is started or until the output data set is closed. When the output data set is 
closed, the standard writer automatically puts out the last record of its last 
input data set. 
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Punch Output 

Normally, when the standard writer is using a card punch as the output device, 
the last three output records are not in the collection pockets of the punch 
when the input data set is closed. To put out these three records with the rest 
of the data set and with no intervening pauses, the writer provides for three 
blank records following the actual data set records. 

Printer Output 

When the standard writer uses a printer as an output device, the last record 
of the input data set is not normally put in the output data set when the 
input data set is closed. To force out this last record, the writer generates a 
blank record that follows the last record of the actual data set. 

The problem of overprinting the last line of one data set by the first line of the 
following data set must also be considered. Depending on the combination of 
input record control character and required output record control character, a 
line of blanks and a spacing control character may be used either individually or 
in combination to preclude overprinting. (Note: If overprinting is desired for 
some reason, control characters in the data set records themselves may be used to 
override the eflFect (but not the action) of the previously described solutions to 
overprinting. ) 

CHECKPOINTING OUTPUT DATA SETS 

If the system output writer procedure specifies a sysout data set checkpoint 
interval, each sysout data set using that writer procedure is checkpointed at 
the specified intervals. Should the system be re-iPLed with warmstart prior to 
completion of writing out a data set, the operator (in reply to message ief595d 
DDD WTR, RESUME AT CHECKPOINT — REPLY Y OR N ) Can specify that the Writing of 
the data set resume at the last checkpoint or at the beginning of the data set. 

CLOSING INPUT DATA SET(s) 

After the standard writer finishes putting out the records of an input data set, 
it closes the data set before returning control to the system output writer. You 
must close all input data sets. 

RELEASING STORAGE 

The storage and buffer areas obtained for the writer must be released to the 
system before the writer relinquishes control. The freemain macro instruction 
should be used for this. 

RESTORING REGISTER CONTENTS 

The original contents of general registers through 12, and 14 must be restored. 
The RETURN macro instruction is used for this. To inform the operating system of 
the results of the processing done by the writer, a return code is placed in 
general register 15 before control is returned. If the writer routine terminates 
because of an unrecoverable error on the output data set, the return code is 8; 
otherwise, the return code is 0. Unrecoverable input errors must be handled by 
the data set writer. 



Control Character Transformations 



To help determine what you can do with a writer routine, the control character 
transformation features of the standard writer are described. 

Effectively there are nine control character combinations that can occur be- 
tween input data set records and output data set records. Both data sets may 
have records whose control characters are either ansi (American National Stand- 
ards Institute) type (ace) or machine type (mcc), or the records may not con- 
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Figure WWT 2. Control Character Translation for Punch Unit Output 

tain any control characters. However, within any given data set, the records all 
must contain the same form of control character. The standard writer has pro- 
cedures to handle control character transformations for both an output to a card 
punch unit and an output to a pinter unit. 



Card Punch Unit 



If an input data set record does not have a control character, the standard writer 
produces one that indicates output into pocket 1 of the punch. If the output unit 
is a tape unit and the ultimate destination is a punch unit, the standard writer 
assumes that the punch unit is either a 2540 or a 2520 unit and sets a control 
character accordingly. The standard writer translation of punch-type control 
characters is given in Figure vtwt 2. In this table, the first three columns of figures 
are machine control character codes, and the right hand column of figures repre- 
sents ANSI control character codes. Each record that requires a control character 
has one of these 8-bit codes attached to it. Input records whose control characters 
are mcc and are shown in horizontal rows 1, 2, 5, and 6 are given the ace code of 
'V if they are placed in an output data set that has ace. An mcc given in rows 3 or 
4 is changed to an ace code of 'W. However, if translation is from an ace input to 
an mcc output, the standard writer translates the control character into the appro- 
priate mcc on the same horizontal row. 



Printer Unit 



When the output unit is a printer, the standard writer prevents overprinting 
between data sets. If the successive data sets contain records with the same type 
of control character, there is no overprinting problem. If the control characters 
vary from one data set to the next, the standard writer solutions are applications of 
the technique illustrated by Figure m^wt 3. In this figure, the possible forms of the 
input record control characters are given in the left hand column. The three right 
hand columns (containing cases 1-9) represent the possible forms of the output 
record control characters. Within each of the 12 main sections of the figure is 
shown a symbolic representation of a data set whose records possess the indicated 
form of control character. Each record consists of a print line representation and 
a control character representation (where appropriate). For records with ace, 
the control character is shown preceding the print line, since the effect of the 
control character occurs before the line is printed. For records with mcc, the 
converse is shown. An input record with no control character is treated as if it 
had an ace. Because of this variance in the printer's mechanical action, whenever 
there is a control character transformation, the standard writer places a trans- 
formed control character with an output data set record other than the record 
to which the character was attached in the input data set. 
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v = Writer generated. 

* = No control character on input causes the standard writer to generate an ANSI control character as indicated. 

Bq = A print line of blanks. 

C-j-Cn = Control characters of records 1-N of a given data set. 

P-j-Pp^ = Print lines of a given data set. 

S-| = A control character causing a 1-line space. 

Sq = A contro' character causing spacing to be suppressed. 

Sn = A control character causing a skip to channel 1. 

Figure WWT 3. Symbolic Representation of Record Formats 



In Figure wwt 3, cases 1 and 5 represent situations in which there is the same 
type o£ control character in the output as there is in the input. Thus, for records 1 
through n, there is no change in the record format. However, there is a provision 
to allow for the possibiHty that two consecutive input data sets may have different 
control characters. In this case, a minimum separation between the data sets as 
they appear in the output data set is provided as indicated by the printing of 
blanks and suppressing the spacing of the printer to allow another control char- 
acter to take effect. The 'extra' record (Sc Bo or Bo Sc) provides the more impor- 
tant function of forcing out the last record of the current data set before the 
writer's processing of that data set is done. 

In cases 2 and 4 of Figure vs^wt 3, the output data set records have different con- 
trol characters than the input data set records. Case 2 shows that the standard 
writer generates a 1-line space control character to precede the first print line of the 
output. When the output is written, each control character of an input record is 
then attached to the next record. The last input record control character (Cn) is at- 
tached to a line of blanks ( Bo ) . In case 4, the first input record control character 
is attached to a line of blanks, and each of the other control characters is attached 
to a preceding record, as indicated. The last input record (Pn) has a writer- 
generated space 1-line control character attached to it before the buffering and 
forcing record (Bo Sc) generated by the writer is put out. 
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Cases 7 and 8 show that the standard writer first generates a 'skip to channel 1' 
control character and then generates 1 line space' control characters for all but the 
last control character. The last control character is the space suppression character 
shown as part of the buffering or forcing record generated. 

Cases 3, 6, and 9 show that if no control characters are required in the output 
data set, the records are printed consecutively and a line of blanks generated by 
the writer is printed after the final record in a data set. Any control characters 
appearing in the input data set are dropped in the output data set. 

Notice that in all cases involving control characters in the output data set, the 
standard writer allows for ( 1 ) an output record to force the printing of the last 
record of an input data set and ( 2 ) a means of minimum buffering between data 
sets by using generated control characters and print lines in conjunction with the 
actual data set control characters. 

The standard writer translation of printer-type control characters is given in 
Figure wwt 4. In this table, the type of action indicated is given in the left-hand 
column. The middle column and the right-hand column show, respectively, the 
bit settings of the control character byte for machine type and ansi type control 
characters corresponding to the entries in the left-hand column. A control charac- 
ter transformation is effected by changing the bit-configuration of the control 
character byte as indicated in the table. 

When machine control characters are used which indicate spacing or skipping 
without writing (bit 6 set to 1, for example, write and space 0-00000011) the 
standard writer generates the indicated ansi control character and also generates 
a blank record of the proper type and length. 
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Figure WWT 4. Control Character Translation for Printer Unit Output 
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Appendix A: Theory of Operation 



Figure apa 1 describes the overall processing flow 
through each job cycle. The paragraphs in the figures 
describe the processing performed by various com- 
ponents of the control program as it loads the nucleus, 
reads control statements, initiates the job step, causes 
processing to begin or end in other partitions, and 
terminates the job step. 
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To load the nucleus, the operator sets the LOAD UNIT 
f.vitches to the device on which the system residence 
-olume is mounted and presses the LOAD button on the 
operator control panel. This causes an IPL record to be 
lead and to be given control. This record causes the 
'econd IPL record to be read, which in turn, enables the 
I' st of the IPL program to be read into real storage. 

The IPL program searches the volume label of the system 
ic-sidence volume to locate the volume table of contents 
I'-'TOC). The VTOC is then searched for the address of the 
nucleus data set (SYSl . NUCLEUS). The nucleus is brought 
; ito the system area, and NIP is brought into the pageable 
area. NIP receives control from the IPL program. It performs 
both required and optional initialization for control program 
operation including initializing the Communication Vector 
Table (CVT), and general system initialization, such as 
determining user options. After completing its processing, 
NIP passes control to the master scheduler task (MST) which 
initializes virtual storage, including JES . 

Partitions are established by the master scheduler at 
system initialization according to the sizes and job class{es) 
tstablished at system generation by the PARTITNS macro 
instruction. The MST also places a copy of the Initiator/ 
Terminator into each partition. The communications task 
receives control from the MST and communicates with the 
operator to request any partition changes. After the 
ti-quested changes, if any, have been made by the definition 
routines, the work queues are initialized. The automatic 
commands are displayed, and the READY message is 
issued . 
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Figure APA 1. VSl Theory of Operation (Part 1 of 4) 
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When the required SET command is entered, the com- 
munications task calls the master scheduler command 
scheduling routine to have the command executed. An 
automatic START reader command or a subsequent operator- 
entered START reader command initiates a reader previously 
loaded in the pageable supervisor area. If a START writer 
command is entered, a writer is initiated and made dis- 
patchable in the pageable supervisor area. 

When the reader gets control, it reads control state- 
ments, commands, data, and procedures from the input 
stream. This information is placed on the appropriate 
direct-access storage device data set (SYSl .SYSPOOL). 
Information from the JOB, EXEC, and DD statements 
controls the execution of each job step. 

The reader also builds disk entry records and accounting 
records for each job and places them in the input work 
queue (SYSl .SYSJOBQE) corresponding to the CLASS 
parameter of the JOB statement. 

After the reader has completed processing all input for 
a job and has entered the job on an input work queue, all 
initiators that are waiting for that job class are posted. 
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After receiving control, the initiator prepares to 
initiate the highest priority job in its primary input work 
queue. Using Information that the reader extracted from 
the DD statement, the initiator processes the user accounting 
routine and then passes control to the interpreter, which 
runs as a subroutine of the initiator. The interpreter 
locates and interprets the JCL for the job and builds the 
following tables: 

• Job control table (JCT) for the job being read. 

• Step control table (SCT) for the step being read. 

• Data set enqueue table (DSENQ) for the job being read. 

• Job file control block (JFCB) and step input/output 
table (SiOT) for each data set being used or created 
by the job step . 

• Volume table (VOLT) containing each volume serial 
number to be used by the job. 

• Other tables are constructed if needed to completely 
interpret the JCL for the job. 

The interpreter places these tables and control blocks in 
the Scheduler Work Area Data Set (SWADS). Information 
from these tables and control blocks is updated with 
information in the data control block (DCB) and data set 
control block (DSCB) or volume label when a data set is 
opened during step execution . 
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Glossary 



active page: A page in real storage that can be addressed. 

active page queue: A queue of pages in real storage that are 
currently assigned to tasks. Pages on this queue are eligible 
for placement on the available page queue. See also available 
page queue, hold page queue. 

address translation: The process of changing the address of 
a data item or an instruction from its virtual address to its 
real storage address. See also dynamic address translation. 

available page queue: A queue of the pages whose real storage 
is currently available for allocation to any task. See also active 
page queue, hold page queue. 



extended control (EC) mode: A mode in which all the features 
of a System/370 computing system, including dynamic address 
translation, are operational. See also basic control (BC) mode. 

external page address: An address that identifies the location of 
a page in a page data set. This address is computed from the 
page number each time a page is to be transferred between 
real storage and external page storage. 

external page storage: The portion of auxiliary storage that is 
used to contain pages. 

external page storage management: A set of routines in the 
paging supervisor that control external page storage. 



basic control (BC) mode: A mode in which the features of a 
System/360 computing system and additional System/370 
features, such as new machine instructions, are operational on 
a System/370 computing system. See also extended control 
(EC) mode. 

BC mode: See basic control mode. 



fixed: In VSl, not capable of being paged out. 

fixed BLDL table: A BLDL table that the user has specified 
to be fixed in the lower portion of real storage. 

fixed page: A page in real storage that is not to be paged out. 



change bit: A bit associated with a page in real storage; the 
change bit is turned on by hardware whenever the associated 
page in real storage is modified. In VSl, there is a change bit 
in the storage key associated with each 2K storage block. 

channel program translation: In a channel program, replacement 
by software of virtual addresses with real addresses. 

control r&gisters: A set of registers used for operating system 
control of relocation, priority interruption, program event re- 
cording, error recovery, and masking operations. 



hold page queue: A queue to which pages in real storage are 
initially assigned through operations such as page-in or page 
reclamation. See also active page queue, available page queue. 



input stream control: See JES reader. 

invalid page: A page that cannot be directly addressed by 
the dynamic address translation feature of the central process- 
ing unit. 



DAT: See dynamic address translation. 

demand paging: Transfer of a page from external page storage 
to real storage at the time it is needed for execution. 

disabled page fault: A page fault that occurs when I/O and ex- 
ternal interruptions are disallowed by the CPU. 

dormant state: A state in which the active pages of a job have 
been paged-out. 

DSS: See dynamic support system. 

dynamic address translation (DAT): (1) The change of a virtual 
storage address to a real storage address during execution of 
an instruction. See also address translation. (2) A hardware 
feature that performs the translation. 

dynamic area: The portion of virtual storage that is divided 
into partitions that are assigned to job steps and system tasks. 
See also pageable dynamic area, nonpageable dynamic area. 

dynamic support system (DSS): An interactive debugging facility 
that allows authorized maintenance personnel to monitor and 
analyze events and alter data. 



EC mode: See extended control mode. 

enabled page fault: A page fault that occurs when I/O and 
external interruptions are allowed by the CPU. 



JECS: See job entry central services. 

/EPS; See job entry peripheral services. 

/£S; See job entry subsystem. 

JES reader: The part of the job entry subsystem that controls 
the input stream and its associated job control statements. 
Synonymous with input stream control. 

/£S writer: The part of the job entry subsystem that controls 
the output of specified data sets. Synonymous with output 
stream control. 

job entry central services (JECS): The part of the job entry 
subsystem that provides centralized storage and retrieval of: 
(1) system input and output data for each job, (2) control tables 
representing jobs, and (3) job tables used during job execution. 

job entry peripheral services (JEPS): The part of the job entry 
subsystem that schedules and performs reader and writer 
operations. 

job entry subsystem (JES): A system facility for spooling, job 
queueing, and managing the scheduler work area data sets. 



lock /unlock facility: A supervisor facility that controls the exe- 
cution of instruction strings when a disabled page fault occurs. 
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■main storage: See real storage, virtual storage. 
memory: See real storage, virtual storage. 
missing page interruption: See page fault. 



nonpageahle dynamic area: An area of virtual storage whose 
virtual addresses are identical to real addresses; it is used for 
programs or parts of programs that are not to be paged during 
execution. Synonymous with V=R dynamic area. 

nonpageahle partition: In VSl, a subdivision of the nonpageable 
dynamic area that is allocated to a job step or system task that 
is not to be paged during execution. In a nonpageable parti- 
tion, each virtual address is identical to its real address. Sy- 
nonymous with V=R partition. 



OS/VS: See Operating System/Virtual Storage. 

Operating System/Virtual Storage: A compatible extension of 
the System/360 Operating System that supports relocation 
hardware and the extended control facilities of System/370. 

OUTLIM (output limiting) facility: A facility that monitors the 
number of logical records produced for SYSOUT data sets. 

output stream control: See JES writer. 



pageable partition: In VSl, a subdivision of the pageable 
dynamic area that is allocated to a job step or system task 
that can be paged during execution. Synon)Tnous with V=V 
partition. 

paging: The process of transferring pages between real and 
external page storage. 

paging device: A direct access storage device on which a page 
data set (and possibly other data sets) are stored. 

paging rate: The average number of page-ins and page-outs per 
unit of time. 

paging supervisor: A part of the supervisor that allocates and 
releases real storage space for pages and initiates page-in and 
page-out operations. 

TCB: See page control block. 

TER: See program event recording. 

TGT: See page table. 

PQA: See protected queue area. 

program event recording (PER): A hardware feature used to 
assist in debugging j^rograms by detecting program events. 

protected queuQ area (PQA): In VSl, an area located at the 
high address end of each virtual storage partition. 



page: (1) A fixed-length block of instructions, data, or both, 
that can be transferred between real storage and external page 
storage. (2) To transfer instructions, data, or both between 
real storage and external page storage. 

page control block (PCB): A control block that indicates the 
status of a paging request. 

page data set: A data set in external page storage, in which 
pages are stored. 

page fault: A program interruption that occurs when a page 
that is marked "not in real storage" is referred to by an active 
page. Synonymous with page translation exception. 

page fixing: Marking a page as nonpageable so that it remains 
in real storage. 

page number: The part of a virtual storage address needed to 
refer to a page. 

page reclamation: The process of making addressable the con- 
tents of a page in real storage that has been marked invalid. 
Page reclamation can occur after a page fault or after a 
request to fix or load a page. 

page table (PGT): A table that indicates whether a page is 
in real storage and correlates virtual addresses with real storage 
addresses. 

page translation exception: A program interruption that occurs 
when a virtual address cannot be translated by the hardware 
because the invalid bit in the page table entry for that address 
is set. Synonymous with page fault. 

page wait: A condition in which the active request block for 
a task is placed in a wait state while a requested page is 
located in real storage or is brought into real storage. 

pageable dynamic area: An area of virtual storage whose ad- 
dresses are not identical to real addresses: it is used for pro- 
grams that can be paged during execution. Synonymous with 
V=V^ dynamic area. 



real address: The address of a location in real storage. 

real storage: Th^ storage of a System/370 computing system 
from which th© central processing unit can directly obtain in- 
structions and data and to which it can directly return results. 

real storage pa^ table (RSPT): In VSl, a table that contains 
an entry for each 2jK storage block in real storage. This table is 
the centralized information interface for real storage manage- 
ment. 

reference bit: A bit associated with a page in real storage; the 
reference bit is turned "ON" by hardware whenever the associ- 
ated page in real stwage is referred to (read or stored into). In 
VSl, there is a reference bit in the storage key associated 
with each 2K storage block. 

relocate hardware: &ee dynamic address translation. 

request parameter list (RPL): A list of parameters that accom- 
panies a request for job entry subsystem services. 



scheduler work, area data set (SWADS): In VSl, a data set on 
auxiliary storage that contains most of the job management con- 
trol blocks (such as the JCT, JFCB, SCT, and SIOT). There is 
one SWADS for each initiator. 

segment: A continuous, 64K area of virtual storage that is allo- 
cated to a job or system task. 

segment table (SGT): A table used in dynamic address transla- 
tion to control user access to virtual storage segments. Each 
entry indicates the length, location, and availability of a corre- 
sponding page table. 

segment table entry (STE): An entry in the segment table that 
indicates the length, location, and availability of a corresponding 
page table. 

segment translation exception: A program interruption that 
occurs when a virtual address cannot be translated by the 
hardware because the invalid bit in the segment table entry 
for that address is set. 



GLO 2 OS/VS 1 Planning and Use Guide 



SGT: See segment table. 

space record: A record that separates page slots in a page 
data set. 

SQA: See system queue area. 

STE: See segment table entry. 

static CP area: In VSl, those portions of virtual storage that 
are allocated, during system generation and initial program load, 
to control program functions. 

storage block: A 2K block of real storage to which a storage key 
can be assigned. 

supervisor lock: An indicator used to inhibit entry to disabled 
code while a disabled page fault is being resolved. 

SWADS: See scheduler work area data set. 

system lock: In VSl, an indicator in the communications vector 
table, used to inhibit the dispatching of any task, except paging 
supervisor tasks. 

system queue area (SQA): An area of virtual storage reserved 
for system-related control blocks. 



thrashing: A condition in which the system can do little useful 
work because of excessive paging. 

translation tables: Page tables and segment tables. 



virtual address: An address that refers to virtual storage and 
must, therefore, be translated into a real storage address when 
it is used. 

virtual equals real (V=R) storage: An area of virtual storage 
that has the same range of addresses as real storage and is 
used for a program or part of a program that cannot be paged 
during execution. 

V=fl dynamic area: See nonpageable dynamic area. 

Y—R partition: See nonpageable partition. 

V=V dynamic area: See pageable dynamic area. 

virtual storage: Addressable space, that appears to the user as 
real storage, from which instructions and data are mapped into 
real storage locations. The size of virtual storage is limited by 
the addressing scheme of the computing system and by the 
amount of auxiliary storage available, rather than by the actual 
number of real storage loctions. 

virtual storage partition: In VSl, a division of the dynamic area 
of virtual storage, established at system generation. 



working set: The set of a user's pages that must be active in 
order to avoid excessive paging. 
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